FiscoBridge Help Main Site

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:

{
  "message": "Invoice validation failed",
  "fieldErrors": [
    {
      "property": "items[2].labels",
      "errors": [
        "Invalid tax labels — tax labels sent are not defined on the SDC (2310)"
      ]
    }
  ]
}

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

{
  "status": 402,
  "detail": "Invoice limit reached. 3000 of 3000 invoices used. Upgrade your package to continue fiscalizing."
}

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