Custom Integration: API Errors and Error Codes

Error handling reference for the FiscoBridge POS API. For endpoints and request schemas, see the API Reference.

HTTP Status Codes

Status	When	What to do
400 Bad Request	The request body is malformed or a required field (`invoiceRequest`, `payment`) is missing, or invalid query parameters (e.g. daily-report range over 62 days)	Fix the request shape
401 Unauthorized	Missing/malformed `X-Api-Key`, unknown client ID, wrong secret, revoked key, or revoked certificate	Check the header format `clientId:clientSecret`; create a new key if yours was revoked
402 Payment Required	Your plan's monthly invoice allowance is used up	Upgrade your plan — see Invoice Limits and Usage
422 Unprocessable Entity	The tax authority rejected the invoice (field validation, see below), or a processing rule failed (e.g. refunding a non-signed invoice, invoice not found, no active certificate)	Read the response body and correct the request
429 Too Many Requests	More than 180 requests per minute from your IP	Back off and retry with spacing

Error Response Shapes

Field validation (422) — the tax authority rejected one or more fields. Each error message ends with the numeric code in parentheses:

Processing error (422) and quota (402) — a standard problem response with the reason in detail:

Model validation (400) — the standard ASP.NET validation problem format with an errors dictionary keyed by field name.

Tax Authority Validation Codes

These codes come from the tax authority's SDC when it validates your invoice. They always appear inside the fieldErrors of a 422 response, next to the property that caused them.

Code	Meaning	Common causes
2310	Invalid tax labels — tax labels sent are not defined on the SDC	A `labels` letter that doesn't exist for your certificate's country. Fetch the valid set from `GET /api/status`
2800	Field required — this field is mandatory	Missing `payment`, `items`, `labels`, `totalAmount`, or `unitPrice`; missing `referentDocumentNumber` on a refund/copy; `buyerCostCenterId` sent without `buyerId`
2801	Value too long — field value exceeds maximum length	`cashier` over 50 chars, `name` over 2048, `requestId` over 32, `buyerId`/`referentDocumentNumber` over their limits
2802	Value too short — field value is below minimum length	e.g. a `gtin` shorter than 8 digits
2803	Invalid field length — field length is outside the expected range	Check the field limits in the API Reference
2804	Value out of range — field value is outside the expected range	Amounts with more than 2 decimal places, negative amounts on a sale, quantity outside 0.001–99,999,999,999.9999, a `referentDocumentDT` in the future
2805	Invalid field value — field contains an invalid value	An enum value that doesn't exist, duplicate letters in `labels`
2806	Invalid data format — field data format is invalid	Dates not in ISO 8601, non-numeric `gtin`
2807	List too short — must contain at least one element	Empty `items` or `payment` array
2808	List too long — exceeds maximum allowed elements	Too many entries in a list field

Tips

Test with invoiceType: "Training" — you get the full validation behavior without issuing real fiscal invoices (training invoices still count toward your monthly allowance)
Don't blind-retry 422s — the same request will fail the same way; fix the reported field first
Do retry 429s and network errors with backoff — but remember create is not idempotent: confirm via GET /api/invoices that the invoice wasn't already signed before re-sending
Read tax labels from GET /api/status at startup instead of hardcoding them — rates and labels can change

Next Steps

API Reference — Endpoints, request fields, and response schemas
Custom Integration — Creating API keys
Invoice limits and usage — Quotas and the 402 response