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, body size, file download links) | 401 / 403 / 404 / 413 / 429 / 503 | Platform envelope {success, errorType, code, message} | code (integer) |
| Companies, NF-e, NFC-e, CT-e, DC-e, NFS-e, invoice e-mail, webhook registration | 400 / 404 / 409 / 500 | Array [{codigo, mensagem}], one entry per problem | codigo (string) |
| NF-e verification and identity lookup | 400 / 404 / 409 / 422 / 428 / 451 / 500 / 503 | Bare object {code, message} | code (integer) |
| Offline NFC-e open API endpoints | 200 / 400 / 404 | Platform envelope; business errors are HTTP 200 as well | code (integer) |
| Invoice Assistant local interface | 400 / 404 / 409 / 429 / 500 / 503; authentication 401 / 403 | Business errors as array [{codigo, mensagem}]; authentication errors as platform envelope | codigo / code |
| Embedded SDK | none | Codigo and Tipo of the exception object | Codigo (integer) |
Messages are localized by the Language / Accept-Language headers (default Portuguese). Branch on codes, never on message text. In the array shape every codigo is 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 |
| 10018xxx | NFS-e |
| 10019xxx | DC-e |
| 10021xxx | Invoice e-mail |
| 10022xxx | NFC-e |
| 10029xxx | Offline NFC-e (open API endpoints, device pairing, offline issuing core, SDK, Invoice Assistant) |
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, or the application is in a cooldown | Wait for Retry-After, then retry; if still rejected, back off exponentially (start at 1 s, double up to 30 s, add jitter); limits apply per application and per endpoint group, rules and headers in Rate limiting and backoff |
| 413 | 10009027 | Request body exceeds the gateway size limit | Send smaller bodies; for NF-e verification send a single NF-e of at most 1 MB |
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 | 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 | Array or bare | Platform-side fault; array-shape endpoints, verification and identity lookup can all return it | 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 |
|---|---|---|---|
| 10003004 | 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 |
| 10003008 | 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 |
| 10003050 | 400 | Automatic registration: CNPJ not found in the public registry data | Check the CNPJ |
| 10003051 | 503 | Automatic registration: public registry data unavailable | Retry the same request later |
| 10003052 | 400 | Company tax regime pending confirmation (automatic registration); cannot issue new documents | Send optanteSimplesNacional and mei through Register company with id |
| 10003053 | 400 | Automatic registration: state or city of the address not identified | Use the company registration endpoint |
| 10009033 | 400 | Invalid webhook registration (id mismatch / non-JSON contentType / unknown code in eventos) | Fix as described, see Register webhook |
| 10009010 | 400 | Invalid webhook callback URL; only http / https addresses are accepted | Use a public https address |
| 10009013 | 400 | Webhook callback URL points to a private or reserved network | Use a public address |
| 10009019 | 400 | Webhook callback URL too long | Shorten the URL |
Tax classes
Array format. Class not found is HTTP 404, concurrent change is HTTP 409, the rest HTTP 400. All codes in Tax classes.
| Error code | HTTP | Scenario | Action |
|---|---|---|---|
| 10005200 | 404 | Code missing or deleted | Check the code and empresaId |
| 10005203 | 400 | Unsupported tax code | Fix per the tax code tables in Issue NF-e |
| 10005204 | 400 | Classification does not belong to the CST | The first three digits of the classification must equal the CST |
| 10005206 | 409 | Class modified concurrently | Read it again and resend |
| 10005208 | 400 | codigo in the creation or whole-replacement body | Remove codigo: the platform generates the code, returns it on creation and it goes in the path afterwards |
| 10005210 | 400 | Unknown field in the body; mensagem names the path | Remove the field; valid names are on the endpoint page |
| 10005211 | 400 | Two rows of the same group with the same combination of cenario, tipoPessoa and naoContribuinte | Merge or remove one of the rows |
| 10005212 | 400 | First digit of the row cfop not matching the scenario | Fit the CFOP to the scenario: outbound 5 / 6 / 7, inbound 1 / 2 / 3 |
| 10005213 | 400 | Number or boolean sent as text; mensagem names the path | Send numbers as JSON numbers and booleans as true / false |
| 10005214 | 400 | CFOP outside its group: ISSQN only with 5933, ICMS never with 5933 | Fit the CFOP to the group |
| 10005216 | 400 | tipo different from the current one on update | The type does not change; create another class |
| 10005217 | 400 | NFCe class with a field NFC-e issuance does not have; mensagem names the path | Remove the field, or create an NFe class |
| 10005218 | 400 | Group the type does not allow: issqn on NFe, ipi on NFCe | Remove the group |
| 10005219 | 400 | NFCe class with a scenario outside SaidaDentroEstado / Padrao | Fix the scenario |
| 10004047 | 400 | Non-taxpayer or individual ICMS row with a taxpayer-only code (10, 30, 70, 101, 201, 202, 203) or percentualCreditoSimples | Use 102 / 500 or another code, or drop the dimension |
| 10005008 | 400 | PIS / COFINS 01 row whose aliquota differs from the statutory rate of the PIS/COFINS regime set on the company | Use the statutory rate or omit it; see "Tax regime" in Companies |
| 10004046 | 400 | Code incompatible with the company regime (CRT 1/4 needs a 3-digit CSOSN, CRT 2/3 a 2-digit CST) | Fit the code to the company regime |
NF-e
Array shape. Business errors are HTTP 400; an unknown document is HTTP 404 with codigo 10004000 or 10004001. 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 |
|---|---|---|---|
| 10004000 / 10004001 | 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 |
| 10004051 | 400 | IBGE code missing and it could not be filled from the CEP: the CEP is not in the reference data, maps to more than one municipality, or belongs to another state | Send the IBGE code or check cep / uf |
| 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 |
| 10005007 | 400 | CRT 3 company with no PIS / COFINS rate on CST 01 and no PIS/COFINS regime set, so the platform cannot fill it | Send aliquota, or set the regime in the console under "Tax settings"; see Companies |
| 10005008 | 400 | CRT 3 company with a PIS / COFINS rate on CST 01 other than the statutory rate of its PIS/COFINS regime | Use the statutory rate or omit it; see Companies |
| 10005202 | 400 | The tax class referenced on the line is missing, deleted or from another company | Check classeImposto and empresaId, see Tax classes |
| 10005215 | 400 | Class of another type: NF-e only references NFe classes and NFC-e only NFCe classes | Reference a class of the right type |
| 10005220 | 400 | The referenced class is incompatible with the current company regime (IncompativelComRegime) | Replace the whole class under the new regime, see Tax classes |
| 10001002 | 400 | A line with classeImposto sends icms or issqn without cfop | Send cfop on that line |
| 10005209 | 400 | The referenced class has no row for this invoice in a group the line needs (ICMS or service-line ISSQN, PIS, COFINS); mensagem gives the group, scenario, customer type and whether the buyer is a non-taxpayer | Add a row to the class, or send the group in the request; see the selection order in Tax classes |
NFC-e
Array shape. Business errors are HTTP 400; an unknown document or company is HTTP 404. SEFAZ rejections are not HTTP errors: they surface as query status Negada and the nfce.rejected webhook. See NFC-e.
| codigo | HTTP | Scenario | Action |
|---|---|---|---|
| 10022006 | 404 | nfceId does not exist | Check the id and the empresaId |
| 10003000 | 404 | empresaId does not exist | Check the empresaId |
| 10022001 | 400 | NFC-e not enabled for the company current environment | Send that environment in emissaoNFeConsumidor on registration or update |
| 10022002 | 400 | The company cannot issue (not approved or certificate unavailable) | Wait for approval or upload the certificate |
| 10022003 | 400 | ambienteEmissao differs from the company current environment | Submit in the company environment |
| 10022004 | 400 | Violates an NFC-e rule; mensagem names it | Fix it, or issue an NF-e |
| 10022007 | 400 | Cancellation deadline passed (30 minutes for cancellation, 168 hours for substitution) | Follow the state rule and issue a reversing NF-e |
| 10022008 | 400 | The status does not allow it (not authorized, cancellation in progress) | Query to confirm the status |
| 10022009 | 400 | The state requires QR code v2 and the company has no usable CSC | QR code v2 is switched on by the platform and the CSC only takes effect in production; contact the platform |
| 10022024 | 400 | IBGE code missing and it could not be filled from the CEP: the CEP is not in the reference data, maps to more than one municipality, or belongs to another state | Send the IBGE code or check cep / uf |
| 10001001 | 400 | Request field validation failed | Fix as per mensagem |
| 10005000 | 400 | The tax engine rejected the request | Fix as per mensagem |
| 10005007 | 400 | CRT 3 company with no PIS / COFINS rate on CST 01 and no PIS/COFINS regime set, so the platform cannot fill it | Send aliquota, or set the regime in the console under "Tax settings"; see Companies |
| 10005008 | 400 | CRT 3 company with a PIS / COFINS rate on CST 01 other than the statutory rate of its PIS/COFINS regime | Use the statutory rate or omit it; see Companies |
| 10005202 | 400 | The tax class referenced on the line is missing, deleted or from another company | Check classeImposto and empresaId, see Tax classes |
| 10005215 | 400 | Class of another type: NF-e only references NFe classes and NFC-e only NFCe classes | Reference a class of the right type |
| 10005220 | 400 | The referenced class is incompatible with the current company regime (IncompativelComRegime) | Replace the whole class under the new regime, see Tax classes |
| 10001002 | 400 | A line with classeImposto sends icms or issqn without cfop | Send cfop on that line |
| 10005209 | 400 | The referenced class has no row for this invoice in a group the line needs (ICMS or service-line ISSQN, PIS, COFINS); mensagem gives the group, scenario, customer type and whether the buyer is a non-taxpayer | Add a row to the class, or send the group in the request; see the selection order in Tax classes |
| 10005205 | 400 | The chosen row of the class has a group or field NFC-e does not accept; mensagem names the field | Create a separate class for NFC-e, or send that group in the request |
Common 10022004 reasons: presence not allowed; delivery or pickup place out of state, or the buyer is a taxpayer; amount above the cap; identification missing; delivery without carrier or address, or carrier or freight on a non-delivery sale; delivery not allowed in the state; CFOP or tax code outside the NFC-e list; underpayment, wrong change or SemPagamento, or a card terminal or description on a payment type that does not accept it; fields NFC-e does not accept (all listed at once); unknown value names.
Common SEFAZ rejections (echoed as is in motivoStatus): 704 issue time more than 5 minutes before SEFAZ received it; 717 presence not allowed; 725 CFOP not allowed; 750 identification threshold reached without identifying the consumer; 780 above the state cap; 785 / 786 / 787 / 788 delivery not allowed in the state, delivery without carrier, without consumer, without address; 462 / 463 / 464 CSC not registered, revoked, QR code check mismatch; 865 payments below the invoice total.
Offline NFC-e
See Offline NFC-e.
Open API endpoints
Platform envelope. Business errors are HTTP 200 with success = false; a missing company or device is HTTP 404; field validation failure is HTTP 400.
| Code | HTTP | Scenario | Action |
|---|---|---|---|
| 10029100 | 404 | Company does not exist or belongs to another integrator | Check empresaId |
| 10029202 | 404 | Device does not exist or belongs to another company | Check dispositivoId |
| 10029101 | 200 | The company cannot issue NFC-e: not yet approved by the platform, rejected or disabled, NFC-e not enabled in the chosen environment, or no valid A1 certificate for production; message gives the reason | A newly registered company must wait for platform approval before enabling offline issuance and generating pairing codes; if rejected, fix it per the reason and resubmit; send emissaoNFeConsumidor at registration; link a valid certificate |
| 10029104 | 200 | Offline issuing for the company disabled by the platform | Contact the platform |
| 10029201 | 200 | The company already has 20 pending pairing codes | Use them first or wait for them to expire |
| 10029219 | 200 | ambiente differs from the company current environment | Generate the code in the company current environment |
| 10029221 | 200 | serie between 890 and 999; NFC-e of a CNPJ issuer only uses series 0 to 889 | Use a series from 0 to 889 |
| 10029222 | 200 | serie is the company profile NFC-e series in one of the environments | Choose another series |
| 10029223 | 200 | serie is held by another active device or a pending code of the company; message says which | Choose another series |
| 10029224 | 200 | numeroInicial is not greater than the highest number known on the series; message gives that number | Send a higher start number, or omit it to continue after that number |
| 10029225 | 200 | serie belongs to a deactivated or revoked device that still has offline invoices to upload | Generate the code after the old device finishes uploading |
| 10029001 | 200 | Parameter out of range; message names the field | Fix it with an allowed value |
| 10001001 | 400 | Request field validation failed | Fix as described in message |
Device pairing
Returned by the platform when the Invoice Assistant or the SDK pairs; the Invoice Assistant setup wizard and the SDK exception show them as is.
| Code | Scenario | Action |
|---|---|---|
| 10029203 / 10029204 | Device deactivated / revoked by the platform | Generate a new pairing code |
| 10029205 | Invalid pairing code | Check it was copied in full; generate a new one if needed |
| 10029206 / 10029207 / 10029208 | Pairing code expired / already used / revoked | Generate a new pairing code |
| 10029209 | The code does not allow this form (for example an Assistente code used by the SDK) | Generate a new code for the right form |
| 10029210 | SDK pairing without the POS software name | Pass the POS software name at initialization |
| 10029501 | POS software blocked by the platform | Contact the platform |
| 10029211 | POS version blocked or below the minimum | Upgrade the POS |
| 10029212 | Core version too old | Upgrade the Invoice Assistant or the SDK |
| 10029213 | Certificate CNPJ differs from the company | Use the A1 certificate of that company |
| 10029214 | Certificate expired | Use a valid certificate |
| 10029219 | Code environment differs from the company current environment (checked again at pairing) | Generate a new code in the company current environment |
| 10029221 to 10029225 | The device series set in the code is checked again at pairing and is no longer available; same meaning as at code generation | Generate a new code with another series or start number |
| 10029307 | Device environment differs from the company current environment: after an environment switch, online issuing and uploads of the old device are refused | Generate a code in the current environment, pair a new device and deactivate the old one |
| 10029424 | Number already taken in device online issuing; returned when the core dropped the number, retried once and still conflicts | The local database and the platform records disagree; export the logs and contact the platform |
| 10029426 | In device online issuing, the same id already has a non-rejected invoice on the platform | Check the original invoice; use a new id for a new sale |
Offline issuing core and SDK
The Invoice Assistant and the embedded SDK share the offline issuing core. Core errors are thrown as exceptions in the SDK (Codigo is the error code, Tipo the constant) and returned as codigo by the Invoice Assistant local interface. The 10029800 and 10029780 blocks come from the core and the 10029870 block from the SDK and the runtime communication; codes that only appear because of a defect in the SDK itself are not listed here, see the SDK reference. Error codes returned by the platform are passed through unchanged.
| Code | Constant | Scenario | Action |
|---|---|---|---|
| 10029780 | ENGINE_TAX_CLASS_REQUIRES_ONLINE | An item line references a tax class, but the platform cannot be reached to expand it; no invoice number was used; the Invoice Assistant returns HTTP 400 | Resend with the same id once the connection is back; when offline, send impostos on the item lines, see Tax classes and connectivity |
| 10029801 | ENGINE_NOT_ACTIVATED | The company is not paired on this machine, or no company is paired yet | Guide the user to pairing; with several companies, check empresaId |
| 10029802 | ENGINE_EMPRESA_REQUIRED | Several companies are paired but empresaId was not given | Send empresaId |
| 10029803 | ENGINE_LICENSE_MISSING | No license available for offline issuing | Sync once while online (SincronizarAgora) |
| 10029804 | ENGINE_LICENSE_EXPIRED | License expired; offline issuing is refused, online issuing works as usual | Restore the network; the license renews itself |
| 10029805 | ENGINE_LICENSE_SIGNATURE_INVALID | Invalid license signature | Manual action: contact the platform, the local store may have been tampered with |
| 10029806 | ENGINE_LICENSE_NOT_FOR_DEVICE | The license does not belong to this device | Manual action: pair again |
| 10029807 | ENGINE_OFFLINE_WINDOW_CLOSED | Offline issuing deadline has passed | Restore the network and issue online |
| 10029808 | ENGINE_LICENSE_QUOTA_EXHAUSTED | Device series numbers used up to 999999999 | Deactivate the device and pair it again with a new pairing code that sets a new series in serie; the platform does not change the series by itself |
| 10029809 | ENGINE_CLOCK_ROLLBACK | The system clock was moved back | Manual action: fix the system time |
| 10029810 | ENGINE_TRANSMISSION_DEADLINE_REACHED | The oldest pending invoice is past the upload deadline | Manual action: restore the network and upload as soon as possible |
| 10029811 | ENGINE_OFFLINE_NOT_ALLOWED | The company or the state does not allow offline issuing; or the device was just restored from a backup and has not received a new license yet | Issue online only; after a restore, offline issuing resumes automatically after one online sync |
| 10029812 | ENGINE_OFFLINE_FUEL_NOT_SUPPORTED | Invoices with fuel cannot be issued offline | Issue once the network is back |
| 10029813 | ENGINE_CERTIFICATE_UNAVAILABLE | Certificate not found, without private key, or CNPJ mismatch | Manual action: check the certificate store; use TrocarCertificado if needed |
| 10029814 | ENGINE_CERTIFICATE_EXPIRED | Certificate expired | Manual action: renew it, then TrocarCertificado |
| 10029815 | ENGINE_SNAPSHOT_MISSING | Local configuration or tax data missing or invalid | Sync while online; if it persists, contact the platform |
| 10029816 | ENGINE_DEVICE_DEACTIVATED | Device deactivated | Manual action: contact the integrator; offline invoices already issued are still uploaded |
| 10029817 | ENGINE_REQUEST_INVALID | Request validation failed; Detalhes lists the reason per field | Fix the request; Previsualizar can pre-validate it |
| 10029818 | ENGINE_DUPLICATE_ID_DIFFERENT_CONTENT | The same id was already used for an invoice with different content | Use a new id for a new sale; retry with the original request to get the original invoice back |
| 10029819 | ENGINE_NOTE_NOT_FOUND | This machine has no such invoice | Check id and empresaId |
| 10029820 | ENGINE_NOTE_NOT_CORRECTABLE | The current status does not allow correction | Only Rejeitada can go through Substituir |
| 10029821 | ENGINE_CORRECTION_CHANGES_TOTALS | The correction changed amounts or taxes | Change only non-amount content |
| 10029822 | ENGINE_CANCEL_NOT_ALLOWED | The current status does not allow cancellation; for cancellation by substitution, the original is not a normal document issued online (an offline document, already cancelled, or with a pending cancellation) | Do not retry |
| 10029823 | ENGINE_SERIE_EXHAUSTED | Device series numbers used up | Deactivate the device and pair it again with a new pairing code that sets a new series in serie; the platform does not change the series by itself |
| 10029824 | ENGINE_PLATFORM_UNREACHABLE | An operation that needs the network (pairing) cannot reach the platform | Check the network and retry |
| 10029825 | ENGINE_ACTIVATION_CODE_INVALID | Pairing code format, signature or validity is wrong | Manual action: generate a new pairing code |
| 10029826 | ENGINE_ACTIVATION_HOST_UNTRUSTED | The pairing code points to an untrusted platform address | Manual action: confirm where the code came from and the installer environment (testing / production) |
| 10029827 | ENGINE_KEY_PROTECTION_FAILED | The data directory comes from another computer or another Windows user | Manual action: run on the original computer and user, or pair again |
| 10029828 | ENGINE_DATA_DIR_LOCKED | The data directory is in use by another process, including, when restoring a backup, an instance of this program on which Encerrar has not been called | Close the other instance; call Encerrar before restoring a backup |
| 10029829 | ENGINE_LOCAL_STORE_CORRUPTED | Local store inconsistent | Manual action: do not delete the data directory, contact the platform |
| 10029830 | ENGINE_PROTOCOL_VERSION_UNSUPPORTED | SDK and runtime versions are incompatible | Upgrade the SDK and the runtime together |
| 10029831 | ENGINE_RUNTIME_START_FAILED | The runtime failed to start | Check that the runtime directory is complete and not blocked by antivirus software |
| 10029832 | ENGINE_RUNTIME_CRASHED | The runtime exited unexpectedly | Retry; with automatic restart on, the SDK recovers by itself; resend issuances with the same id |
| 10029833 | ENGINE_TIMEOUT | Timed out waiting | Resend the issuance with the same id, or call Consultar first |
| 10029834 | ENGINE_SHUTTING_DOWN | Shutting down or already shut down | Call Iniciar again |
| 10029835 | ENGINE_IN_PROCESS_UNSUPPORTED | Java in-process mode requires Java 21 or later | Use subprocess mode |
| 10029836 | ENGINE_INTERNAL_ERROR | Internal core error; the message carries a reference number | Contact the platform with the reference number and the logs |
| 10029837 | ENGINE_ALREADY_ACTIVATED | The company is already paired in this data directory | No need to pair again; to change devices, deactivate the old one first |
| 10029838 | ENGINE_PLATFORM_RESPONSE_UNTRUSTED | Platform response failed verification; the previous data was kept | Retried automatically later; if it persists, check whether a network proxy is rewriting responses |
| 10029839 | ENGINE_ACTIVATION_PERSIST_FAILED | Paired on the platform but local saving failed | Pair again with the same pairing code |
| 10029840 | ENGINE_CONFIG_INVALID | Invalid initialization configuration | Fix the configuration |
| 10029841 | ENGINE_AUTHORIZED_XML_UNAVAILABLE | Authorized XML unavailable: not yet authorized, or not stored locally and could not be fetched from the platform | Fetch it after the authorization event; if it could not be fetched, retry later |
| 10029842 | ENGINE_LOCAL_STORE_NEWER_VERSION | The data directory was used by a newer version and the core refuses to start; the Invoice Assistant local interface returns HTTP 503 | Install or upgrade to a version no older than the last one used; do not delete the data directory |
| 10029843 | ENGINE_CANCEL_XML_UNAVAILABLE | Cancellation XML unavailable: not yet cancelled, or not stored locally and could not be fetched from the platform | Fetch it after the cancellation success event; if it could not be fetched, retry later |
| 10029844 | ENGINE_EXPORT_FAILED | Writing the export or backup file failed: the destination is not writable, or the backup file already exists | Use another directory or file name; check disk space and permissions |
| 10029845 | ENGINE_SUBSTITUTE_KEY_INVALID | The substitute document key for cancellation by substitution is invalid, or is not a non-rejected offline document of this company on this device | Send the 44-digit key of the offline document this device issued for the same sale |
| 10029846 | ENGINE_BACKUP_INVALID | The backup cannot be restored: wrong passphrase, or the backup file was altered, is corrupted or is not an offline issuing backup; the Invoice Assistant returns HTTP 400 | Check the backup passphrase; use an intact backup. The original database stays unchanged |
| 10029874 | ENGINE_PARAMS_INVALID | Parameter missing or of the wrong type; Detalhes.campo names the parameter | Fix the parameter, for example a request that is not a JSON object, the certificate thumbprint format or the date format |
| 10029877 | ENGINE_RUNTIME_NOT_FOUND | Runtime not found | Check the installer and the runtime directory |
| 10029878 | ENGINE_TOO_MANY_PENDING | More than 64 calls waiting at the same time | Reduce concurrency |
| 10029880 | ENGINE_PRINCIPAL_UNREACHABLE | A secondary in primary/secondary mode cannot reach the primary; the request did not get there | Retry later, or move the till to the backup machine |
| 10029881 | ENGINE_PRINCIPAL_RESULT_UNKNOWN | The request reached the primary but no response came back; the result is unknown | After the primary recovers, query with the same id; reissuing with the same id and content does not issue twice |
| 10029882 | ENGINE_TERMINAL_TOKEN_INVALID | The terminal token of the secondary is invalid or revoked | Issue a new terminal token on the primary and update the secondary configuration |
| 10029883 | ENGINE_PRINCIPAL_ADDRESS_INVALID | The primary address is badly formatted or not a private local network address | Fix the primary address in the secondary configuration |
| 10029884 | ENGINE_MODE_METHOD_UNAVAILABLE | The current mode does not offer this method | Pairing, certificate change, backup and export run on the primary; terminal management is primary only |
| 10029885 | ENGINE_PRINCIPAL_REJECTED | The primary rejected the request source, for example a secondary outside the allowed networks | Check the primary's allowed networks and the network |
| 10029886 | ENGINE_PRINCIPAL_RATE_LIMITED | Too many failed authentications; rate-limited by the primary | Check the token and retry after 1 minute |
| 10029887 | ENGINE_PRINCIPAL_LISTEN_FAILED | The local network port of the primary cannot be opened | Change the primary port or free the port |
| 10029888 | ENGINE_TERMINAL_NOT_FOUND | The terminal to revoke does not exist | Check the terminal identifier |
Invoice Assistant
| Code | HTTP | Scenario | Action |
|---|---|---|---|
| 10029900 | 401 | Cashier token missing | Send Authorization: Bearer tfl_… |
| 10029901 | 401 | Cashier token invalid or revoked | The store manager generates a new token |
| 10029902 | 403 | The token has no access to this company | Generate a token that includes the company |
| 10029903 | 403 | Source address outside the allowed local network ranges | Check the local network mode settings |
| 10029904 | 400 | Invalid callback URL | Only http / https; with local network mode off, only loopback addresses |
| 10029905 | 401 | Desktop program action requires a manager session | Log in with the manager PIN |
| 10029906 | 401 | Wrong manager PIN | Type it again; 5 wrong attempts in total lock it |
| 10029907 | 409 | Printer unavailable | Check the printer connection and the printer chosen in Settings |
| 10029908 | 409 | Setup wizard not finished | Finish the setup wizard first |
| 10029909 | 400 | Invalid request | Fix as described in mensagem |
| 10029910 | 404 | Resource not found | Check the path |
| 10029911 | 400 | Invalid PIN format; it must be 6 to 8 digits | Set it again in that format |
| 10029912 | 500 | Internal assistant error | Export the diagnostics package and contact the platform |
| 10029913 | 403 | Host header of a desktop program request not allowed; only 127.0.0.1, localhost or [::1] plus the assistant port are accepted | Open the desktop program at http://127.0.0.1:port, not through a proxy or another host name |
| 10029914 | 429 | Too many wrong PIN attempts; locked | Wait for the lock to end, see the Invoice Assistant FAQ |
| 10029916 | 409 | Chosen port is taken or cannot be listened on; settings unchanged | Choose another port |
| 10029917 | 403 | Cashier session has no access to this company | Log in with the manager PIN to do it |
| 10029918 | 429 | Assistant busy: 3 XML fetches are already in progress, or an export or backup is already in progress | Retry later; do not repeat the call in quick succession |
| 10029919 | 400 | Invalid outbound proxy settings | Correct "Internet connection" and "Address" of the outbound proxy in the desktop program's "Settings" as prompted; the settings were not saved |
| 10029920 | 409 | Saving the outbound proxy or restoring from a backup needs the issuing core to restart, but an export, backup or XML download in progress did not finish within 15 seconds | Wait for those operations to finish, then save or restore again; neither the settings nor the local database were changed |
| 10029922 | 409 | Less than 256 MB free on the disk holding the assistant's data directory; the export, backup or backup file upload was refused | Free up space on that disk and retry |
| 10029923 | 403 | A desktop program request has a missing or wrong anti-forgery token, usually because the session expired or the page was left open too long | Refresh the page; if it persists, sign in again with the manager PIN |
| 10029924 | 429 | Cashier sessions opened too often; at most 20 per minute from the same origin | Wait a minute before opening the issuing page again |
Invoice Assistant errors only appear in the assistant's local interface and desktop program; the embedded SDK never returns them; 10029905 to 10029908, 10029911, 10029913 to 10029917 and 10029919 to 10029924 only appear in the desktop program.
CT-e
Array shape. Business errors are HTTP 400; a missing document / task is HTTP 404 with codigo 10017002 or 10017003. SEFAZ rejections during issuance surface as query status Negada and the cte.rejected webhook. See CT-e.
| codigo | HTTP | Scenario | Action |
|---|---|---|---|
| 10017002 / 10017003 | 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 |
| 10017050 | 400 | codigoIbge missing and it could not be filled from the CEP: cep absent, not in the reference data, or maps to more than one municipality | Send codigoIbge or check cep |
| 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 10019002 or 10019003. 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 |
|---|---|---|---|
| 10019002 / 10019003 | 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 |
| 10019012 / 10019010 | 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 |
| 10019014 | 400 | Marketplace / Carrier company without remetente | Add the sender |
| 10019015 | 400 | remetente.endereco missing | Add the sender address |
| 10019016 | 400 | Brazilian sender without cpfCnpj | Add the sender document |
| 10019004 | 400 | Company cannot issue (not approved / certificate not ready) | Wait for approval / link the certificate |
| 10019017 | 400 | Brazilian recipient without cpfCnpj | Add the recipient document |
| 10019011 | 400 | Municipality IBGE code not found or inconsistent with uf | Check cidade / uf |
| 10019049 | 400 | IBGE code missing and it could not be filled from the CEP: the CEP is not in the reference data, maps to more than one municipality, or belongs to another state | Send the IBGE code or check cep / 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 |
NFS-e
Array shape [{codigo, mensagem}]; business errors are HTTP 400 and a missing document is HTTP 404 with codigo 10018002 or 10018003. Issuance is asynchronous: a refusal at acceptance is a synchronous HTTP error, while a refusal by the authority shows up as a Negada query result plus the nfse.rejected webhook. See NFS-e.
| codigo | HTTP | Scenario | What to do |
|---|---|---|---|
| 10018001 | 400 | Parameter validation refused at acceptance; mensagem states the reason (IBS/CBS gate not in force, a São Paulo issuer sending ibsCbs, a code or structural constraint not met) | Fix as mensagem says |
| 10018002 / 10018003 | 404 | Document not found: nfseId does not belong to this issuer, or the inbound key is not among its received invoices | Check nfseId / chaveAcesso against empresaId |
| 10018004 | 400 | Issuer not eligible (disabled / certificate unusable) | Check issuer status and certificate |
| 10018005 | 400 | Issuer has no NFS-e profile; mensagem names the missing item | Send emissaoNFSe at registration or update with id |
| 10018010 | 400 | The municipality's NFS-e standard is not supported yet | That municipality cannot issue yet, contact the platform |
| 10018012 | 400 | Service code is not in the official LC 116 list | Check codigoTributacaoNacional |
| 10018013 | 400 | Recipient document is invalid | Check the CPF / CNPJ / NIF |
| 10018014 | 400 | Service export is missing the destination country | Add servico.paisPrestacao |
| 10018015 | 400 | The replaced document cannot be replaced | Check the status of the replaced document |
| 10018020 | 400 | ISS rate could not be resolved (no inline value or municipal parameter) | Send servico.iss.aliquota or the right servico.codigoTributacaoMunicipal |
| 10018022 | 400 | A Simples issuer must not send the ISS rate directly | Remove aliquota |
| 10018023 | 400 | Federal withholding cannot be determined yet; provide the following or send the withheld amounts: %s. %s lists at once the paths of every missing field: servico.retencoes.categoriaFederal, cliente.orgaoPublico, cliente.optanteSimplesNacional, servico.retencoes.modoContratacao, servico.retencoes.anexoSimples, servico.retencoes.inss/irrf/csll/pis/cofins | Provide the listed fields and resend, or send the withheld amounts in servico.retencoes, zero when there is none; when the list names servico.retencoes.inss/irrf/csll/pis/cofins, only sending the amounts works, as happens when the service classification needs manual review or this company files as the recipient or the intermediary |
| 10018030 / 10018031 | 400 | The same request is already being processed / that order already has an invoice or the same id carries different content | Retry later; use another order number or check the content |
| 10018040 | 400 | A cancellation review is already in progress | Wait for the municipal verdict |
| 10018041 | 400 | The document has already been replaced | No further operation is allowed |
| 10018042 | 400 | The current status does not allow this event (cancellation; manifestation: cancelled / replaced / already manifested / this issuer is neither recipient nor intermediary) | Check the document status; each party manifests once per invoice |
| 10018063 | 400 | The DPS message does not comply with the official XSD; details carry line, column, error key and element name | Usually text outside Latin-1, an incomplete address, or a value outside the official code table |
| 10018064 | 400 | The NFS-e event message does not comply with the official XSD | Check motivo length (15-255), the codigoMotivo value and the character set |
| 10018065 | 400 | The NFS-e tax reference data this invoice needs has not been imported; send the fields after the arrow in the request, or import the reference data first: %s. %s lists each item with an arrow to the request field that replaces it: retencao-federal -> servico.retencoes.inss/irrf/csll/pis/cofins, pis-cofins -> servico.pisCofins.aliquotaPis/aliquotaCofins, iss-local-incidencia -> servico.iss.municipioIncidencia.codigoIbge; it only appears when an item the request left out must be looked up by the platform, and always at acceptance | Send the fields after the arrow in the request, or ask the platform to confirm the reference data is imported; iss-local-incidencia appears when the place of supply is in another municipality, and sending servico.iss.municipioIncidencia is enough |
| 10018066 | 400 | IBGE code missing and it could not be filled from the CEP: the CEP is not in the reference data, maps to more than one municipality, or belongs to another state | Send the IBGE code or check cep / uf |
Invoice e-mail
Array shape. Business errors are HTTP 400; not found is HTTP 404; a previous e-mail for the same document not yet final is HTTP 409. A delivery failure is not an HTTP error: it surfaces as query status Falha and the email.failed webhook. See Invoice e-mail.
| Code | HTTP | Case | Action |
|---|---|---|---|
| 10003000 | 404 | empresaId not found | Check empresaId |
| 10021001 | 404 | E-mail template not found or not owned by the integrator | Check templateId |
| 10021002 | 400 | Template disabled, or its document type differs from the document | Use another template or enable it |
| 10021003 | 400 | Template uses a variable outside the allow-list | Fix per the variable enumeration |
| 10021004 | 400 | Template HTML has forbidden content or the body exceeds 64 KB | Fix at the places the message names |
| 10021005 | 400 | Unsupported tipoDocumento in the template list | Send only NFe / NFSe / CTe / DCe |
| 10021010 | 404 | Document not found or not owned by the company | Check documentoId, tipoDocumento and empresaId |
| 10021011 | 400 | Document not authorized yet, or cancelled or replaced | Send after authorization |
| 10021012 | 400 | No default template for this document type | Send templateId or set a default template |
| 10021013 | 400 | No recipient | Send destinatarios |
| 10021015 | 409 | The previous e-mail for this document is not final yet | Wait for Enviado or Falha, then resend with a new id |
| 10021020 | 404 | E-mail not found or not owned by the company | Check emailId and empresaId |
| 10001001 | 400 | Request field validation failed (one entry per field) | Fix per mensagem |
NF-e verification
Bare shape {code, message}, see NF-e verification. Request-level errors of XML verification and the chave lookup are HTTP 400; the request never enters validation:
| 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 |
| 10015003 | XML verification | Encoding is not UTF-8 | Convert to UTF-8 before submitting |
| 10015005 | XML verification | Retired, no longer returned (formerly: chave already submitted for verification by another integrator) | No action needed: each integrator can verify the same invoice independently |
| 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 |
DANFE retrieval
DANFE retrieval failures return the HTTP status below and a bare {code, message} object; errors are JSON even when the request carries Accept: application/pdf.
| code | HTTP | Meaning | Action |
|---|---|---|---|
| 10015104 | 400 | Malformed chave (length / characters / check digit) | Validate locally first: 44 digits; the last digit is a mod-11 check digit |
| 10015300 | 404 | Your account has no verification record for this invoice (a verification by another integrator does not count) | Submit it through XML verification first; do not retry |
| 10015301 | 409 | Verification not finished yet (PENDING_SEFAZ / VALIDATING) | Fetch after receiving invoice.verify.completed |
| 10015302 | 409 | The current verdict produces no PDF (only VALIDATED and invoices with status Cancelada do) | Do not retry |
| 10015303 | 409 | The platform is missing the original XML of this invoice | Resubmit the same XML unchanged through XML verification, without forceRevalidate, then fetch again |
| 10015304 | 503 | The original XML is still being archived | Retry after Retry-After (5 seconds) |
| 10015305 | 503 | Generation is busy or temporarily unavailable | Retry after Retry-After |
| 10001000 | 500 | Internal platform error | Retry with backoff; if persistent, contact the platform with the request timestamp and path |
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 (status null) | Yes, retryable | Platform-side verification failure, not an invoice judgment; like any verdict it is reused for 24 hours, so resubmit later with header forceRevalidate: true |
VALIDATION_ERROR (status Desconhecida) | Yes, retrying will not change it | SEFAZ does not accept queries for this invoice (e.g. cStat 526, issued too long ago); not an invoice judgment, it does not mean the invoice is fake. The verdict is reused, there is no need to retry; confirm by other means if needed |
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: wait for
Retry-After, then retry; if still rejected, back off with exponential delay and jitter (start at 1 s, double up to 30 s); ignoring 429 and resending continuously leads to a cooldown, see Rate limiting and backoff. - 503: retry the same request or link after
Retry-After(10009037, 10015304 / 10015305, 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.
