Reference
Error codes
Consolidated error code reference of the TF Fiscal Open API, grouped by layer and domain, with HTTP status, scenario and recommended handling.
Error shapes
Errors come in three shapes depending on which layer produced them, see General conventions:
| Layer | HTTP | Shape | Code field |
|---|---|---|---|
| Platform gateway (authentication, subscription, rate limit, file download links) | 401 / 403 / 404 / 429 / 503 | Platform envelope {success, errorType, code, message} | code (integer) |
| Companies, NF-e, CT-e, DC-e, webhook registration | 400 / 404 | Array [{codigo, mensagem}], one entry per problem | codigo (string) |
| NF-e verification and identity lookup | 400 / 422 / 428 / 451 / 500 / 503 | Bare object {code, message} | code (integer) |
Messages are localized by the Language / Accept-Language headers (default Portuguese). Branch on codes, never on message text. In the array shape GW001, CER0005, NFe0001, CTe0001, DCe0001 and DCe0000x keep their alphanumeric values; all other codigo values are the platform error code as a numeric string.
Code ranges by domain:
| Range | Domain |
|---|---|
| 10001xxx | Request validation and platform faults |
| 10003xxx | Company and certificate |
| 10004xxx | NF-e issuance, cancellation and correction letter |
| 10005xxx | Tax engine |
| 10009xxx | Open platform (authentication, subscription, rate limit, webhooks, download links) |
| 10013xxx | File download |
| 10015xxx | NF-e verification |
| 10016xxx | Identity lookup (CNPJ / CPF) |
| 10017xxx | CT-e |
| 10019xxx | DC-e |
Gateway: authentication and authorization
Platform envelope shape, produced before the request reaches the API. 401 and 403 are configuration errors; retrying without a fix is pointless and may trip rate limits. See Authentication for the signing scheme.
| HTTP | code | Meaning | Action |
|---|---|---|---|
| 401 | 10009000 | Missing signature headers (token / sign / timestamp) | Send all three headers on every request |
| 401 | 10009001 | Timestamp invalid or clock skew beyond ±300 s | Sync your clock (NTP); regenerate the timestamp per request, never reuse |
| 401 | 10009002 | Invalid token | Check the app_secret; if rotated, update your configuration |
| 401 | 10009003 | Signature mismatch | Re-derive the signature; see the checklist in Authentication |
| 403 | 10009004 | Application disabled | Contact the platform |
| 403 | 10009015 | Application not effective (pending approval or rejected) | Wait for approval / contact the platform |
| 403 | 10009014 | Integrator account disabled | Contact the platform |
| 403 | 10009005 | API not subscribed | Request subscription for the endpoint being called |
| 429 | 10009006 | Rate limit exceeded | Back off and retry (start at 1 s, double up to 30 s, add jitter); limits apply per application and per endpoint group |
Download links (linkDanfe, linkDownloadXml, linkDacce, nfeLinkXml, cteLinkDacte, dceLinkDace and the like) are plain GET requests without signature headers; their failures are HTTP statuses with the platform envelope, see File download:
| HTTP | code | Meaning | Action |
|---|---|---|---|
| 401 | 10009035 | Download link invalid (path altered, token reused or signature mismatch) | Use the link exactly as returned by the query API |
| 401 | 10009036 | Download link expired | Query the document again for a fresh link |
| 503 | 10009037 | File not ready yet (rendering service busy) | Retry the same link after Retry-After |
| 404 | 10013011 | Downloaded file not found | Check where the link came from |
| 429 | 10013016 | Too many downloads from one IP through callback links | Retry after Retry-After |
Request validation and platform faults
| code | HTTP | Shape | Scenario | Action |
|---|---|---|---|---|
| 10001001 | 400 | Array | Request field validation failed, one entry per field; also registration / update contract errors of the emissaoDCe section (both configuration blocks missing, update changing cnpj / municipality, lowering the series cursor, switching series) | Fix per mensagem |
| 10001000 | 500 | Bare | Platform-side fault on a verification or identity call | Retry with backoff; if persistent, contact the platform with the failing timestamp and path |
Companies and certificates
Array shape. See Companies.
| codigo | HTTP | Scenario | Action |
|---|---|---|---|
GW001 | 400 | Registration: city / state cannot be resolved to an IBGE code; issuance: recipient IBGE municipality code does not exist or is inconsistent with uf | Check the UF and city name / IBGE code |
CER0005 | 400 | Certificate password mismatch | Check the password |
| 10003000 | 404 | empresaId does not exist or does not belong to this application | Check the empresaId |
| 10003002 | 400 | CNPJ already registered | The company exists; use the original empresaId |
| 10003006 | 400 | Registration data missing the IE | Provide inscricaoEstadual |
| 10003010 | 400 | Certificate CNPJ does not match the company | Use the correct certificate |
| 10003011 | 400 | Certificate expired | Use a valid certificate |
| 10003012 | 400 | Certificate identical to the currently active one | Nothing to upload |
| 10009033 | 400 | Invalid webhook registration (id mismatch / non-JSON contentType) | Fix as described, see Register webhook |
NF-e
Array shape. Business errors are HTTP 400; an unknown document is HTTP 404 with codigo NFe0001. SEFAZ rejections during issuance are not HTTP errors: they surface as query status Negada and the invoice.rejected webhook. See NF-e.
| codigo | HTTP | Scenario | Action |
|---|---|---|---|
NFe0001 | 404 | The nfeId for query / cancellation / correction letter does not exist | Check the id sent at issuance and the empresaId |
| 10004002 | 400 | Too many pending issuance tasks for the CNPJ | Retry later |
| 10004004 | 400 | Company not issuable (not yet approved or certificate not ready) | Wait for approval / link the certificate |
| 10004012 | 400 | Cancellation / correction letter: invoice not in authorized status | Query to confirm the status |
| 10004013 | 400 | Cancellation: outside the 24-hour window | Issue a return invoice instead |
| 10004014 | 400 | Cancellation: refused by SEFAZ (status code and reason attached) | Act on the SEFAZ reason |
| 10004015 | 400 | Correction letter: 20 letters already registered on the invoice | No further letters; cancel + reissue or return invoice |
| 10004016 | 400 | Correction letter refused by SEFAZ (status code and reason attached) | Act on the SEFAZ reason |
| 10004017 | 400 | Correction letter: fewer than 15 characters after sanitising | Rewrite in Portuguese / ASCII |
| 10004019 | 400 | Correction letter: outside the 720-hour window after authorization | Cancel + reissue or return invoice only |
| 10004021 to 10004026 | 400 | Return invoice references: missing reference / reference on a non-return invoice / original not found or not this company / original not authorized / original item not found / quantity above the original line | See the return invoice rules in Issue NF-e |
| 10004030 | 400 | ambienteEmissao does not match the company's current environment | Submit under the company environment or ask operations to switch it, see Environments |
| 10004031 | 400 | Value not supported (presencaConsumidor / multiple payments / unknown payment type / tipoPessoa inconsistent with the document / CPF buyer carrying inscricaoEstadual) | Adjust to the supported range in Issue NF-e |
| 10004034 | 400 | CNPJ buyer without cliente.inscricaoEstadual | Send the buyer's state registration (ICMS taxpayer) |
| 10004043 | 400 | Contract field missing (base reduction / ST margin and rate / deferral / unit tax amount / IPI code / pCredSN absent from both request and profile); mensagem names the field path | Fill the field per the tax code matrix in Issue NF-e |
| 10004044 | 400 | Field not applicable to the tax code (substituicaoTributaria on a non-ST code, percentualCreditoSimples on a non-credit code) | Remove the group |
| 10004045 | 400 | The CNPJ buyer's cliente.inscricaoEstadual fails the check-digit rule of the buyer's state (SEFAZ would reject with 209 after numbering) | Check the buyer's IE and state |
| 10004046 | 400 | Tax code does not match the company regime (CRT 1/4 needs a 3-digit CSOSN, CRT 2/3 a 2-digit CST) | Use the code family of the company's regime |
| 10004047 | 400 | A non-taxpayer buyer with a taxpayer-only code (10/30/70, 101/201/202/203) or with pCredSN | Use 102 / 500 or 900 without credit |
| 10005000 | 400 | Rejected by the tax engine (regime / tax code mismatch, ST code for a non-taxpayer buyer, rate out of range) | See the tax parameter rules in Issue NF-e |
CT-e
Array shape. Business errors are HTTP 400; a missing document / task is HTTP 404 with codigo CTe0001. SEFAZ rejections during issuance surface as query status Negada and the cte.rejected webhook. See CT-e.
| codigo | HTTP | Scenario | Action |
|---|---|---|---|
CTe0001 | 404 | cteId not found or not owned by the company | Check id and empresaId |
| 10003000 | 404 | empresaId not found | Check empresaId |
| 10017004 | 400 | Company cannot issue (not approved / certificate not ready) | Wait for approval / link the certificate |
| 10017005 / 10017006 | 400 | Concurrent duplicate request / too many pending tasks for the CNPJ | Retry later |
| 10017007 | 400 | Number series unresolved (none configured, or several enabled without a choice) | Configure a model 57 series |
| 10017010 | 400 | ambienteEmissao differs from the company's environment | Submit for the company's environment |
| 10017011 | 400 | Municipality IBGE code not found | Check codigoIbge |
| 10017012 / 10017013 | 400 | Party missing / taker inconsistent with the IE indicator | Add the party or change indicadorIeTomador |
| 10017014 | 400 | Invalid document references (missing, bad check digit, mixed groups, previous documents inconsistent with the service type) | Adjust the references |
| 10017015 | 400 | Document type inconsistent with references (complementary / substitute) | Send ctesComplementados / cteSubstituido per tipo |
| 10017016 | 400 | Components do not sum to the total, or aReceber above the total | Fix the amounts |
| 10017017 / 10017018 / 10017019 | 400 | Invalid RNTRC / unsupported modal / invalid enum or format (mensagem names the field) | Fix per mensagem |
| 10017020 to 10017025 | 400 | Tax parameter missing / not allowed / regime mismatch / icmsUfFim required / rate table row missing / unsupported CST | See the tax parameters in CT-e |
| 10017030 | 400 | Same id with a different message | Use a new id or resend the original message |
| 10017031 | 400 | Production: an active / authorized document already exists for the id | Query the original |
| 10017040 to 10017045 | 400 | Status does not allow the event / cancellation window exceeded / invalid event text / SEFAZ rejected the event / correction sequence limit / referenced event not found | See the cancellation and event rules in CT-e |
| 10017048 / 10017049 | 400 | Cancellation blocked by a registered correction letter / correction letter outside the 720-hour window | See the cancellation and event rules in CT-e |
| 10001001 | 400 | Request field validation failed (one entry per field) | Fix per mensagem |
DC-e
Array shape. Business errors are HTTP 400; a missing document / task is HTTP 404 with codigo DCe0001. Cases with a documented example code keep that code; every other codigo is the platform's numeric error code. SEFAZ rejections during issuance surface as query status Negada and the dce.rejected webhook; SEFAZ rejections of the cancellation surface as dce.cancel_rejected. See DC-e.
| codigo | HTTP | Scenario | Action |
|---|---|---|---|
DCe0001 | 404 | dceId not found, not owned by the company, or cancellation requested before the document was materialized | Check id and empresaId; cancel Pendente documents only after authorization |
| 10003000 | 404 | empresaId not found | Check empresaId |
DCe00004 | 400 | Company not configured for DC-e (missing tipoEmitente / model 99 series / Marketplace site), or ambiente differs from the company's current environment | Send emissaoDCe at registration or through an update with id; submit for the company's current environment and ask operations for the production switch |
DCe00005 | 400 | Marketplace / Carrier company without remetente | Add the sender |
DCe00006 | 400 | remetente.endereco missing | Add the sender address |
DCe00007 | 400 | Brazilian sender without cpfCnpj | Add the sender document |
DCe00008 | 400 | Company cannot issue (not approved / certificate not ready) | Wait for approval / link the certificate |
DCe00009 | 400 | Brazilian recipient without cpfCnpj | Add the recipient document |
GW001 | 400 | Municipality IBGE code not found or inconsistent with uf | Check cidade / uf |
| 10019005 / 10019006 | 400 | Concurrent duplicate request / too many pending tasks for the CNPJ | Retry later |
| 10019007 | 400 | Number series unresolved (several enabled series) | Ask operations to consolidate the series |
| 10019013 | 400 | Issuer type Carrier not supported for issuance yet | Use a Marketplace / OwnIssuer company |
| 10019018 | 400 | Invalid item (NCM length, quantity ≤ 0, negative unit price) | Fix per mensagem |
| 10019019 | 400 | Invalid enum or format (mensagem names the field: tipoPessoa, modalidade, dataEmissao, documents, phone, e-mail, own-issuer remetente differing from the company) | Fix per mensagem |
| 10019020 | 400 | Invalid carrier CNPJ | Fix cnpjTransportadora |
| 10019021 | 400 | Additional information too long | Shorten the text |
| 10019022 | 400 | Invalid autorizacaoDownloadXml count or document; contains the issuer's own CNPJ; duplicate document | Fix the list |
| 10019030 | 400 | Same id with a different message | Use a new id or resend the original message |
| 10019031 | 400 | Production: an active / authorized document already exists for the id | Query the original |
| 10019040 to 10019043 | 400 | Status does not allow cancellation / 24-hour window exceeded / cancellation already accepted / invalid reason | See the cancellation rules in DC-e |
| 10019048 | 400 | dataEmissao outside the allowed window (more than 5 minutes ahead or more than 30 days back; mensagem carries the current limits) | Use the current time or omit dataEmissao |
| 10001001 | 400 | Request field validation failed (one entry per field); registration / update contract errors of emissaoDCe | Fix per mensagem |
NF-e verification
Bare shape {code, message}, HTTP 400. The request never enters validation. See NF-e verification.
| code | Endpoint | Meaning | Action |
|---|---|---|---|
| 10015000 | XML verification | Empty request body | Send the XML in the body |
| 10015001 | XML verification | Body exceeds 1 MB | An authentic single NF-e never exceeds this; check that you are not wrapping or double-encoding |
| 10015002 | XML verification | DTD detected (<!DOCTYPE) | Strip DTDs; they are rejected as an XXE safeguard |
| 10015003 | XML verification | Encoding is not UTF-8 | Convert to UTF-8 before submitting |
| 10015104 | Chave lookup | Malformed chave (length / characters / check digit) | Validate locally first: 44 digits; the last digit is a mod-11 check digit |
| 10015004 | Chave lookup | Invoice not found in any source | The chave is unknown to the platform and the official data source; verify it with its issuer |
Tier-1 validation errors
Returned with HTTP 200 inside validation.errors[] of the XML verification response. These are not transport errors: the request succeeded, the document failed. All are blocking (terminal REJECTED) except PROTOCOL_MISSING, which is a warning.
errors[].code | Numeric | Meaning |
|---|---|---|
XML_MALFORMED | 10015100 | XML syntax invalid |
XSD_INVALID | 10015101 | Does not conform to the NF-e 4.00 XSD layout |
SIGNATURE_INVALID | 10015102 | Digital signature verification failed (content tampered, or certificate expired at signing time) |
SIGNATURE_CERT_MISMATCH | 10015103 | Signing certificate CNPJ does not match the issuer |
ACCESS_KEY_INVALID | 10015104 | chave structure / check digit invalid |
ACCESS_KEY_MISMATCH | 10015105 | chave segments do not match the document fields |
PROTOCOL_MISMATCH | 10015106 | Protocol block inconsistent with the document |
PROTOCOL_MISSING | 10015107 | No protocol node (warning, non-blocking) |
XML_VERSION_UNSUPPORTED | 10015108 | Layout version is not 4.00 |
Tier-2 outcomes
Not HTTP errors: they arrive through the invoice.verify.completed webhook.
validationStatus | Terminal | Action |
|---|---|---|
VALIDATED | Yes | Safe to proceed (release goods, settle) |
REJECTED | Yes | Do not proceed; reason explains the SEFAZ verdict (cancelled / denied / voided / not found / protocol mismatch) |
VALIDATION_ERROR | No | Platform-side verification failure, not an invoice judgment; resubmit later with header forceRevalidate: true |
Identity lookup
Bare shape {code, message}. Format and check-digit errors are rejected locally and never reach the upstream source; they consume no quota and are not billed. See Identity lookup.
| code | HTTP | Responsible party | Meaning | Action |
|---|---|---|---|---|
| 10016000 | 400 | Caller | Invalid CPF format (11 digits required) | Check for stray formatting characters or wrong length |
| 10016001 | 400 | Caller | Invalid CPF check digits | Validate locally with the mod-11 algorithm first |
| 10016002 | 400 | Caller | Invalid date of birth (valid DDMMYYYY required) | Note the day-month-year order, and that the date must actually exist |
| 10016003 | 400 | Caller | CPF not found | The CPF does not exist, or the CPF and date of birth do not match (deliberately indistinguishable) |
| 10016004 | 451 | Third party (lawful upstream block) | LGPD: menor de 16 anos (Lei Felca), holder is under 16 | Data lawfully withheld; do not retry |
| 10016005 | 422 | Third party (lawful upstream block) | LGPD: menor de idade, holder is 16 to 17 | Data lawfully withheld; do not retry |
| 10016006 | 428 | Third party (lawful upstream block) | LGPD: idade nao verificavel - informe a data de nascimento para completar a verificacao, age cannot be verified | The platform already re-verified once with the date of birth; do not retry |
| 10016010 | 400 | Caller | Invalid CNPJ format (14 digits required) | Check for stray formatting characters |
| 10016011 | 400 | Caller | Invalid CNPJ check digits | Validate locally with the mod-11 algorithm first |
| 10016012 | 400 | Caller | CNPJ not found | No such CNPJ in the official registry |
| 10016020 | 503 | Third party (upstream unavailable) | Upstream data source is temporarily unavailable | Retry with exponential backoff (start at 1 s, double up to 30 s, add jitter); contact the platform if it persists |
Handling guidance
- 401 / 403: configuration errors; fix the credential, subscription or clock. Do not retry as-is.
- 400 / 404: the request or the business rule; fix per the code. A few codes are transient and can be retried later: 10004002, 10017005 / 10017006, 10019005 / 10019006.
- 422 / 428 / 451: statutory blocks on identity lookups; retrying is pointless.
- 429: back off with exponential delay and jitter (start at 1 s, double up to 30 s).
- 503: retry the same request or link after
Retry-After(10009037, 10016020). - 5xx: retry with backoff; if persistent, contact the platform with the failing
timestampand path. - Envelope
errorType:1API error,2SEFAZ rejection,3system fault (retryable),4field validation failure (fix the request). - Never retry a rejected document blindly:
NegadaandREJECTEDare terminal verdicts; act on the SEFAZ reason first.