Errors

This guide describes how API errors are classified, what each status code means, and how to read the most common error responses.

Error types

Errors are classified in two levels. If a level 1 validation fails, the API stops the request and returns 400 (Bad Request) with the details of the failures, without running the level 2 validations.

1. Level 1 errors

These are request validation failures, which the API checks before it processes the request. Each failure gives the property that failed (propertyName) and a message that depends on the rule applied. Use the property, not the message text, to identify the failure in your code (see ValidationFailure).

Messages are in Spanish; for example, 'transpInternacId' no debe estar vacío. ('transpInternacId' must not be empty.) Some rule-specific messages and the JSON parsing errors, such as malformed JSON or a value of the wrong type, are in English. For the rule-specific ones, see Stamping validation messages (stamping: the certification by a SAT-authorized provider that makes a CFDI valid).

2. Level 2 errors

These are the checks the SAT (Mexico's tax authority, Servicio de Administración Tributaria) requires for a CFDI (Mexico's electronic invoice) to comply with version 4.0. Their messages are in Spanish and explain the cause according to the SAT specifications. See the CFDI 4.0 error table for the full list.

Status codes

The status code category tells you whether the request succeeded. The response body follows the Fiscalapi response model.

Resource not found

When an endpoint looks up a resource by its ID and the resource doesn't exist in your tenant (the space in Fiscalapi that holds your issuers, recipients, credits, and data), it returns 404. The ID can go in the path, as in Get an invoice by ID, or in the body, as invoiceId in Generate a PDF by ID. Endpoints that have their own message for this case say so in their section, such as tax files (the CSD and e.firma .cer and .key files you upload for a person).

In the messages, <id> is the ID you sent and <catalogName> is the catalog name in the path, which is case-sensitive: satpaymentforms isn't SatPaymentForms.

Fiscalapi checks the catalog name on every route that includes it: GET /api/v4/catalogs/<catalogName>, Get a record by ID, Search a catalog, GET /api/v4/catalogs/<catalogName>/load, and List a catalog for the bulk download (the SAT service that delivers the CFDIs a taxpayer issued and received) catalogs. The valid names are the ones that List catalogs and List bulk download catalogs return.

SAT catalog keys

When a field carries a key that isn't in its SAT catalog, the endpoint returns 400 with a validation failure on that field. The message, in Spanish, includes the value received and the catalog name, without the list of keys.

The rule applies to invoices (POST /api/v4/invoices) and to their cancellation, which rejects the cancellation reason (one of the SAT keys 01 to 04) without calling the PAC (Proveedor Autorizado de Certificación, a SAT-authorized provider that stamps CFDIs). It also applies to CFDI products, to people (person: any individual or legal entity registered in your tenant), both issuers and recipients, and to employee and employer data. Look up the valid keys with the SAT catalogs API.

Each field returns a single failure: in required fields with this rule (for example, versionCode, typeCode, taxes, or payroll keys), an empty or missing value returns only the empty field message. The following fields have their own message, different from the general form:

Values that don't fit in the invoice

When you stamp (POST /api/v4/invoices) and when you calculate (POST /api/v4/invoices/calculate), Fiscalapi builds the invoice it would save and checks that each value fits in it. Stamping here covers an invoice by value (you send every issuer, recipient, and item value in the request) or by reference (you send the IDs of people and products already saved in Fiscalapi), of any CFDI type (the TipoDeComprobante key: I income, the regular sales invoice; E credit note; T transfer, moves goods without a sale; N payroll; P payment), with any complement (complemento, an XML extension the SAT defines for specific operations). A text can't be longer than its maximum, and an amount or a quantity, rounded to its decimal places, can't have more integer digits than allowed. For example, the line item quantity and the payment amount allow 12: values less than 1000000000000.

If a value doesn't fit, the endpoint returns 400 with a validation failure for each value, without stamping and without using a stamp (one credit, used each time you stamp a CFDI). When you stamp, the check happens before Fiscalapi deducts the stamp and calls the PAC; calculating never stamps or uses a stamp.

In this failure, propertyName is the path of the value in the saved invoice, not the path of the request field:

Other possible paths include, for example:

Rules specific to the request fields (for example, a recipient email of up to 256 characters or an itemSku of up to 100) are checked first, and their failure is on the request field.

Decimal places in amounts, quantities, and rates

When you stamp (POST /api/v4/invoices, by value or by reference) and when you calculate (POST /api/v4/invoices/calculate), the amounts, quantities, and rates that go into the XML as is allow at most the decimal places the SAT defines for their attribute (the XSD of CFDI 4.0 and its complements). A value with more decimal places returns 400 with a validation failure for each value, before Fiscalapi deducts the stamp and calls the PAC:

Fiscalapi doesn't round the value: round it in your system to the right number of decimal places before you send it. For example, to 6 decimal places:

Only significant decimal places count, not trailing zeros. For example, 0.16000000 in taxRate and an exchange rate of 1.0000000 with the MXN currency are accepted. The limits, by XML attribute, are:

The rule applies to the field even when, in a specific invoice, its value doesn't reach the XML (for example, totalInstallments and dailyAmount together with totalOneTime). It doesn't apply to the fields that Fiscalapi rounds when it builds the XML (the amount of other payroll payments, local taxes, and Comercio Exterior amounts), or to the Carta Porte and Comercio Exterior fields, which validate their decimal places with their own message.

The daysPaid field (the days paid in the payroll) accepts an integer or up to 3 decimal places. Fiscalapi writes it to the XML as the SAT requires: as an integer, or with exactly 3 decimal places.

Fiscalapi writes some numbers with its own scale, such as the rate or fixed amount and the exchange rate with MXN, so extra zeros in those fields don't reach the XML. The PAC rejects an amount that goes into the XML as is with extra zeros (for example, 200.0000000 in unitPrice) with CFDI40999: send at most the attribute's decimal places.

Stamping validation messages

When you stamp (POST /api/v4/invoices, by value or by reference) and when you calculate (POST /api/v4/invoices/calculate), validation messages are in Spanish and name the field as the API does: in camelCase, the same as in the JSON. The other endpoints name the field with the property name split into words.

The failure field (propertyName) is the path of the value in the request, in PascalCase (for example, Items[0].ItemTaxes[0].TaxCode). Use it, not the text, to identify the failure (see ValidationFailure).

These stamping rules have their own message. In the messages, <campo> (<field>) is the field name as the API writes it; for example, 'date'. <régimen> (<regime>) and <uso> (<use>) are the recipient's keys, and the person type, legal entity (persona moral) or individual (persona física), is the one that matches the length of the recipient's RFC (Mexico's taxpayer ID, Registro Federal de Contribuyentes).

An invoice with more than 1,500 line items returns 400 without a validation failure, both when you stamp and when you calculate:

The Carta Porte and Comercio Exterior catalog messages, the certificate file messages, and the JSON parser messages (malformed JSON or a value of the wrong type) are in English. For example:

Null elements in lists

Each element of a list of objects in the body must be an object. A null element, as in "relatedInvoices": [null] or "productTaxes": [{ ... }, null], returns 400 with a validation failure for each null element:

This check runs before the other validations and before Fiscalapi calls the PAC: the response includes only the null element failures, without stamping or using a stamp. If the body also can't be read (for example, a value of the wrong type), the response includes only the parsing failure.

When you stamp and when you calculate, the message names the field as the API does, in camelCase. The other endpoints name it with the property name split into words.

A null element returns only this failure, at its position, also in the lists that have their own rule: taxCredentials (the certificate pair and the empty list), paidInvoices and paidInvoiceTaxes (the empty list), and the Carta Porte locations (minimum 2).

Lists of strings (for example, validationTypes in SAT validations) keep their own rule. The metadata field is a dictionary, not a list: it accepts null values.

Certificates and private keys

Endpoints that receive a private key (.key file) with its password open the key before they use it. If the password doesn't open the key, they return 400 with a validation failure on the password field. The same failure occurs if the file sent as the key isn't a private key: reading the key doesn't tell the two cases apart. The check happens before Fiscalapi calls the PAC and without using a stamp.

The cancellation by value (with taxCredentials) doesn't open the key: it sends the key to the PAC, which returns its own error if the password doesn't match.

Other certificate and key errors:

The 500 is a server error, not a request error: repeating the request with other data doesn't fix it, so contact support.

Server errors

Changing the request data doesn't fix a server error (5xx). The response includes traceIdentifier (see ApiResponse): include it when you contact support, because it identifies the request in Fiscalapi's logs. The message field tells you which side the cause is on:

The PAC rejection when you stamp or cancel, the 425 (Too Early) of Download a package by ID, and the 429 (Too Many Requests) of the rate limit keep their own message. Server errors respond as follows:

Example (unexpected error):

{
  "data": null,
  "succeeded": false,
  "message": "Something went wrong on our end.",
  "details": "Ocurrió un error inesperado en el servidor. Escríbenos a soporte@fiscalapi.com con el traceIdentifier de esta respuesta.",
  "httpStatusCode": 500,
  "traceIdentifier": "5C1E0B7A92D44F3E8A6B1D07F3C29E41"
}

Uncertain stamping result

When you stamp, if the PAC doesn't respond in time or returns a server error without a rejection code, the result is uncertain: the CFDI may have been stamped. Fiscalapi returns the unexpected error (500) and keeps the stamp used and the invoice's folio number (the issuer's own sequential number for the CFDI; not the UUID) to reconcile them; it doesn't refund them.

Don't resend the invoice right away, because you could stamp the same transaction twice. Check your invoices with List invoices and, if the invoice isn't there, contact support with the traceIdentifier of the response. A PAC rejection with its code is a rejection: Fiscalapi refunds the stamp, and the response includes the PAC's message.

Data constraints and concurrency

When it writes the data, Fiscalapi's database also rejects what the request caused and a field validation didn't catch earlier. These responses are client errors and include no validation failure or field: the reason is in details, in Spanish.

On a 409, fetch the record again and repeat the request. People keep their own 409 (see Update an issuer). Any other database failure returns the unexpected error (500).

Specific errors

The full tables of level 2 errors are on these pages: