TF Fiscal
Documentation

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:

LayerHTTPShapeCode field
Platform gateway (authentication, subscription, rate limit, body size, file download links)401 / 403 / 404 / 413 / 429 / 503Platform envelope {success, errorType, code, message}code (integer)
Companies, NF-e, NFC-e, CT-e, DC-e, NFS-e, invoice e-mail, webhook registration400 / 404 / 409 / 500Array [{codigo, mensagem}], one entry per problemcodigo (string)
NF-e verification and identity lookup400 / 404 / 409 / 422 / 428 / 451 / 500 / 503Bare object {code, message}code (integer)
Offline NFC-e open API endpoints200 / 400 / 404Platform envelope; business errors are HTTP 200 as wellcode (integer)
Invoice Assistant local interface400 / 404 / 409 / 429 / 500 / 503; authentication 401 / 403Business errors as array [{codigo, mensagem}]; authentication errors as platform envelopecodigo / code
Embedded SDKnoneCodigo and Tipo of the exception objectCodigo (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:

RangeDomain
10001xxxRequest validation and platform faults
10003xxxCompany and certificate
10004xxxNF-e issuance, cancellation and correction letter
10005xxxTax engine
10009xxxOpen platform (authentication, subscription, rate limit, webhooks, download links)
10013xxxFile download
10015xxxNF-e verification
10016xxxIdentity lookup (CNPJ / CPF)
10017xxxCT-e
10018xxxNFS-e
10019xxxDC-e
10021xxxInvoice e-mail
10022xxxNFC-e
10029xxxOffline 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.

HTTPcodeMeaningAction
40110009000Missing signature headers (token / sign / timestamp)Send all three headers on every request
40110009001Timestamp invalid or clock skew beyond ±300 sSync your clock (NTP); regenerate the timestamp per request, never reuse
40110009002Invalid tokenCheck the app_secret; if rotated, update your configuration
40110009003Signature mismatchRe-derive the signature; see the checklist in Authentication
40310009004Application disabledContact the platform
40310009015Application not effective (pending approval or rejected)Wait for approval / contact the platform
40310009014Integrator account disabledContact the platform
40310009005API not subscribedRequest subscription for the endpoint being called
42910009006Rate limit exceeded, or the application is in a cooldownWait 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
41310009027Request body exceeds the gateway size limitSend 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:

HTTPcodeMeaningAction
40110009035Download link invalid (path altered, token reused or signature mismatch)Use the link exactly as returned by the query API
40110009036Download link expiredQuery the document again for a fresh link
50310009037File not ready yetRetry the same link after Retry-After
40410013011Downloaded file not foundCheck where the link came from
42910013016Too many downloads from one IP through callback linksRetry after Retry-After

Request validation and platform faults

codeHTTPShapeScenarioAction
10001001400ArrayRequest 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
10001000500Array or barePlatform-side fault; array-shape endpoints, verification and identity lookup can all return itRetry with backoff; if persistent, contact the platform with the failing timestamp and path

Companies and certificates

Array shape. See Companies.

codigoHTTPScenarioAction
10003004400Registration: city / state cannot be resolved to an IBGE code; issuance: recipient IBGE municipality code does not exist or is inconsistent with ufCheck the UF and city name / IBGE code
10003008400Certificate password mismatchCheck the password
10003000404empresaId does not exist or does not belong to this applicationCheck the empresaId
10003002400CNPJ already registeredThe company exists; use the original empresaId
10003006400Registration data missing the IEProvide inscricaoEstadual
10003010400Certificate CNPJ does not match the companyUse the correct certificate
10003011400Certificate expiredUse a valid certificate
10003012400Certificate identical to the currently active oneNothing to upload
10003050400Automatic registration: CNPJ not found in the public registry dataCheck the CNPJ
10003051503Automatic registration: public registry data unavailableRetry the same request later
10003052400Company tax regime pending confirmation (automatic registration); cannot issue new documentsSend optanteSimplesNacional and mei through Register company with id
10003053400Automatic registration: state or city of the address not identifiedUse the company registration endpoint
10009033400Invalid webhook registration (id mismatch / non-JSON contentType / unknown code in eventos)Fix as described, see Register webhook
10009010400Invalid webhook callback URL; only http / https addresses are acceptedUse a public https address
10009013400Webhook callback URL points to a private or reserved networkUse a public address
10009019400Webhook callback URL too longShorten 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 codeHTTPScenarioAction
10005200404Code missing or deletedCheck the code and empresaId
10005203400Unsupported tax codeFix per the tax code tables in Issue NF-e
10005204400Classification does not belong to the CSTThe first three digits of the classification must equal the CST
10005206409Class modified concurrentlyRead it again and resend
10005208400codigo in the creation or whole-replacement bodyRemove codigo: the platform generates the code, returns it on creation and it goes in the path afterwards
10005210400Unknown field in the body; mensagem names the pathRemove the field; valid names are on the endpoint page
10005211400Two rows of the same group with the same combination of cenario, tipoPessoa and naoContribuinteMerge or remove one of the rows
10005212400First digit of the row cfop not matching the scenarioFit the CFOP to the scenario: outbound 5 / 6 / 7, inbound 1 / 2 / 3
10005213400Number or boolean sent as text; mensagem names the pathSend numbers as JSON numbers and booleans as true / false
10005214400CFOP outside its group: ISSQN only with 5933, ICMS never with 5933Fit the CFOP to the group
10005216400tipo different from the current one on updateThe type does not change; create another class
10005217400NFCe class with a field NFC-e issuance does not have; mensagem names the pathRemove the field, or create an NFe class
10005218400Group the type does not allow: issqn on NFe, ipi on NFCeRemove the group
10005219400NFCe class with a scenario outside SaidaDentroEstado / PadraoFix the scenario
10004047400Non-taxpayer or individual ICMS row with a taxpayer-only code (10, 30, 70, 101, 201, 202, 203) or percentualCreditoSimplesUse 102 / 500 or another code, or drop the dimension
10005008400PIS / COFINS 01 row whose aliquota differs from the statutory rate of the PIS/COFINS regime set on the companyUse the statutory rate or omit it; see "Tax regime" in Companies
10004046400Code 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.

codigoHTTPScenarioAction
10004000 / 10004001404The nfeId for query / cancellation / correction letter does not existCheck the id sent at issuance and the empresaId
10004002400Too many pending issuance tasks for the CNPJRetry later
10004004400Company not issuable (not yet approved or certificate not ready)Wait for approval / link the certificate
10004012400Cancellation / correction letter: invoice not in authorized statusQuery to confirm the status
10004013400Cancellation: outside the 24-hour windowIssue a return invoice instead
10004014400Cancellation: refused by SEFAZ (status code and reason attached)Act on the SEFAZ reason
10004015400Correction letter: 20 letters already registered on the invoiceNo further letters; cancel + reissue or return invoice
10004016400Correction letter refused by SEFAZ (status code and reason attached)Act on the SEFAZ reason
10004017400Correction letter: fewer than 15 characters after sanitisingRewrite in Portuguese / ASCII
10004019400Correction letter: outside the 720-hour window after authorizationCancel + reissue or return invoice only
10004021 to 10004026400Return 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 lineSee the return invoice rules in Issue NF-e
10004030400ambienteEmissao does not match the company's current environmentSubmit under the company environment or ask operations to switch it, see Environments
10004031400Value 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
10004034400CNPJ buyer without cliente.inscricaoEstadualSend the buyer's state registration (ICMS taxpayer)
10004043400Contract 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 pathFill the field per the tax code matrix in Issue NF-e
10004044400Field not applicable to the tax code (substituicaoTributaria on a non-ST code, percentualCreditoSimples on a non-credit code)Remove the group
10004045400The 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
10004046400Tax 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
10004047400A non-taxpayer buyer with a taxpayer-only code (10/30/70, 101/201/202/203) or with pCredSNUse 102 / 500 or 900 without credit
10004051400IBGE 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 stateSend the IBGE code or check cep / uf
10005000400Rejected 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
10005007400CRT 3 company with no PIS / COFINS rate on CST 01 and no PIS/COFINS regime set, so the platform cannot fill itSend aliquota, or set the regime in the console under "Tax settings"; see Companies
10005008400CRT 3 company with a PIS / COFINS rate on CST 01 other than the statutory rate of its PIS/COFINS regimeUse the statutory rate or omit it; see Companies
10005202400The tax class referenced on the line is missing, deleted or from another companyCheck classeImposto and empresaId, see Tax classes
10005215400Class of another type: NF-e only references NFe classes and NFC-e only NFCe classesReference a class of the right type
10005220400The referenced class is incompatible with the current company regime (IncompativelComRegime)Replace the whole class under the new regime, see Tax classes
10001002400A line with classeImposto sends icms or issqn without cfopSend cfop on that line
10005209400The 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-taxpayerAdd 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.

codigoHTTPScenarioAction
10022006404nfceId does not existCheck the id and the empresaId
10003000404empresaId does not existCheck the empresaId
10022001400NFC-e not enabled for the company current environmentSend that environment in emissaoNFeConsumidor on registration or update
10022002400The company cannot issue (not approved or certificate unavailable)Wait for approval or upload the certificate
10022003400ambienteEmissao differs from the company current environmentSubmit in the company environment
10022004400Violates an NFC-e rule; mensagem names itFix it, or issue an NF-e
10022007400Cancellation deadline passed (30 minutes for cancellation, 168 hours for substitution)Follow the state rule and issue a reversing NF-e
10022008400The status does not allow it (not authorized, cancellation in progress)Query to confirm the status
10022009400The state requires QR code v2 and the company has no usable CSCQR code v2 is switched on by the platform and the CSC only takes effect in production; contact the platform
10022024400IBGE 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 stateSend the IBGE code or check cep / uf
10001001400Request field validation failedFix as per mensagem
10005000400The tax engine rejected the requestFix as per mensagem
10005007400CRT 3 company with no PIS / COFINS rate on CST 01 and no PIS/COFINS regime set, so the platform cannot fill itSend aliquota, or set the regime in the console under "Tax settings"; see Companies
10005008400CRT 3 company with a PIS / COFINS rate on CST 01 other than the statutory rate of its PIS/COFINS regimeUse the statutory rate or omit it; see Companies
10005202400The tax class referenced on the line is missing, deleted or from another companyCheck classeImposto and empresaId, see Tax classes
10005215400Class of another type: NF-e only references NFe classes and NFC-e only NFCe classesReference a class of the right type
10005220400The referenced class is incompatible with the current company regime (IncompativelComRegime)Replace the whole class under the new regime, see Tax classes
10001002400A line with classeImposto sends icms or issqn without cfopSend cfop on that line
10005209400The 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-taxpayerAdd a row to the class, or send the group in the request; see the selection order in Tax classes
10005205400The chosen row of the class has a group or field NFC-e does not accept; mensagem names the fieldCreate 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.

CodeHTTPScenarioAction
10029100404Company does not exist or belongs to another integratorCheck empresaId
10029202404Device does not exist or belongs to another companyCheck dispositivoId
10029101200The 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 reasonA 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
10029104200Offline issuing for the company disabled by the platformContact the platform
10029201200The company already has 20 pending pairing codesUse them first or wait for them to expire
10029219200ambiente differs from the company current environmentGenerate the code in the company current environment
10029221200serie between 890 and 999; NFC-e of a CNPJ issuer only uses series 0 to 889Use a series from 0 to 889
10029222200serie is the company profile NFC-e series in one of the environmentsChoose another series
10029223200serie is held by another active device or a pending code of the company; message says whichChoose another series
10029224200numeroInicial is not greater than the highest number known on the series; message gives that numberSend a higher start number, or omit it to continue after that number
10029225200serie belongs to a deactivated or revoked device that still has offline invoices to uploadGenerate the code after the old device finishes uploading
10029001200Parameter out of range; message names the fieldFix it with an allowed value
10001001400Request field validation failedFix 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.

CodeScenarioAction
10029203 / 10029204Device deactivated / revoked by the platformGenerate a new pairing code
10029205Invalid pairing codeCheck it was copied in full; generate a new one if needed
10029206 / 10029207 / 10029208Pairing code expired / already used / revokedGenerate a new pairing code
10029209The code does not allow this form (for example an Assistente code used by the SDK)Generate a new code for the right form
10029210SDK pairing without the POS software namePass the POS software name at initialization
10029501POS software blocked by the platformContact the platform
10029211POS version blocked or below the minimumUpgrade the POS
10029212Core version too oldUpgrade the Invoice Assistant or the SDK
10029213Certificate CNPJ differs from the companyUse the A1 certificate of that company
10029214Certificate expiredUse a valid certificate
10029219Code environment differs from the company current environment (checked again at pairing)Generate a new code in the company current environment
10029221 to 10029225The device series set in the code is checked again at pairing and is no longer available; same meaning as at code generationGenerate a new code with another series or start number
10029307Device environment differs from the company current environment: after an environment switch, online issuing and uploads of the old device are refusedGenerate a code in the current environment, pair a new device and deactivate the old one
10029424Number already taken in device online issuing; returned when the core dropped the number, retried once and still conflictsThe local database and the platform records disagree; export the logs and contact the platform
10029426In device online issuing, the same id already has a non-rejected invoice on the platformCheck 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.

CodeConstantScenarioAction
10029780ENGINE_TAX_CLASS_REQUIRES_ONLINEAn 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 400Resend with the same id once the connection is back; when offline, send impostos on the item lines, see Tax classes and connectivity
10029801ENGINE_NOT_ACTIVATEDThe company is not paired on this machine, or no company is paired yetGuide the user to pairing; with several companies, check empresaId
10029802ENGINE_EMPRESA_REQUIREDSeveral companies are paired but empresaId was not givenSend empresaId
10029803ENGINE_LICENSE_MISSINGNo license available for offline issuingSync once while online (SincronizarAgora)
10029804ENGINE_LICENSE_EXPIREDLicense expired; offline issuing is refused, online issuing works as usualRestore the network; the license renews itself
10029805ENGINE_LICENSE_SIGNATURE_INVALIDInvalid license signatureManual action: contact the platform, the local store may have been tampered with
10029806ENGINE_LICENSE_NOT_FOR_DEVICEThe license does not belong to this deviceManual action: pair again
10029807ENGINE_OFFLINE_WINDOW_CLOSEDOffline issuing deadline has passedRestore the network and issue online
10029808ENGINE_LICENSE_QUOTA_EXHAUSTEDDevice series numbers used up to 999999999Deactivate 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
10029809ENGINE_CLOCK_ROLLBACKThe system clock was moved backManual action: fix the system time
10029810ENGINE_TRANSMISSION_DEADLINE_REACHEDThe oldest pending invoice is past the upload deadlineManual action: restore the network and upload as soon as possible
10029811ENGINE_OFFLINE_NOT_ALLOWEDThe 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 yetIssue online only; after a restore, offline issuing resumes automatically after one online sync
10029812ENGINE_OFFLINE_FUEL_NOT_SUPPORTEDInvoices with fuel cannot be issued offlineIssue once the network is back
10029813ENGINE_CERTIFICATE_UNAVAILABLECertificate not found, without private key, or CNPJ mismatchManual action: check the certificate store; use TrocarCertificado if needed
10029814ENGINE_CERTIFICATE_EXPIREDCertificate expiredManual action: renew it, then TrocarCertificado
10029815ENGINE_SNAPSHOT_MISSINGLocal configuration or tax data missing or invalidSync while online; if it persists, contact the platform
10029816ENGINE_DEVICE_DEACTIVATEDDevice deactivatedManual action: contact the integrator; offline invoices already issued are still uploaded
10029817ENGINE_REQUEST_INVALIDRequest validation failed; Detalhes lists the reason per fieldFix the request; Previsualizar can pre-validate it
10029818ENGINE_DUPLICATE_ID_DIFFERENT_CONTENTThe same id was already used for an invoice with different contentUse a new id for a new sale; retry with the original request to get the original invoice back
10029819ENGINE_NOTE_NOT_FOUNDThis machine has no such invoiceCheck id and empresaId
10029820ENGINE_NOTE_NOT_CORRECTABLEThe current status does not allow correctionOnly Rejeitada can go through Substituir
10029821ENGINE_CORRECTION_CHANGES_TOTALSThe correction changed amounts or taxesChange only non-amount content
10029822ENGINE_CANCEL_NOT_ALLOWEDThe 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
10029823ENGINE_SERIE_EXHAUSTEDDevice series numbers used upDeactivate 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
10029824ENGINE_PLATFORM_UNREACHABLEAn operation that needs the network (pairing) cannot reach the platformCheck the network and retry
10029825ENGINE_ACTIVATION_CODE_INVALIDPairing code format, signature or validity is wrongManual action: generate a new pairing code
10029826ENGINE_ACTIVATION_HOST_UNTRUSTEDThe pairing code points to an untrusted platform addressManual action: confirm where the code came from and the installer environment (testing / production)
10029827ENGINE_KEY_PROTECTION_FAILEDThe data directory comes from another computer or another Windows userManual action: run on the original computer and user, or pair again
10029828ENGINE_DATA_DIR_LOCKEDThe data directory is in use by another process, including, when restoring a backup, an instance of this program on which Encerrar has not been calledClose the other instance; call Encerrar before restoring a backup
10029829ENGINE_LOCAL_STORE_CORRUPTEDLocal store inconsistentManual action: do not delete the data directory, contact the platform
10029830ENGINE_PROTOCOL_VERSION_UNSUPPORTEDSDK and runtime versions are incompatibleUpgrade the SDK and the runtime together
10029831ENGINE_RUNTIME_START_FAILEDThe runtime failed to startCheck that the runtime directory is complete and not blocked by antivirus software
10029832ENGINE_RUNTIME_CRASHEDThe runtime exited unexpectedlyRetry; with automatic restart on, the SDK recovers by itself; resend issuances with the same id
10029833ENGINE_TIMEOUTTimed out waitingResend the issuance with the same id, or call Consultar first
10029834ENGINE_SHUTTING_DOWNShutting down or already shut downCall Iniciar again
10029835ENGINE_IN_PROCESS_UNSUPPORTEDJava in-process mode requires Java 21 or laterUse subprocess mode
10029836ENGINE_INTERNAL_ERRORInternal core error; the message carries a reference numberContact the platform with the reference number and the logs
10029837ENGINE_ALREADY_ACTIVATEDThe company is already paired in this data directoryNo need to pair again; to change devices, deactivate the old one first
10029838ENGINE_PLATFORM_RESPONSE_UNTRUSTEDPlatform response failed verification; the previous data was keptRetried automatically later; if it persists, check whether a network proxy is rewriting responses
10029839ENGINE_ACTIVATION_PERSIST_FAILEDPaired on the platform but local saving failedPair again with the same pairing code
10029840ENGINE_CONFIG_INVALIDInvalid initialization configurationFix the configuration
10029841ENGINE_AUTHORIZED_XML_UNAVAILABLEAuthorized XML unavailable: not yet authorized, or not stored locally and could not be fetched from the platformFetch it after the authorization event; if it could not be fetched, retry later
10029842ENGINE_LOCAL_STORE_NEWER_VERSIONThe data directory was used by a newer version and the core refuses to start; the Invoice Assistant local interface returns HTTP 503Install or upgrade to a version no older than the last one used; do not delete the data directory
10029843ENGINE_CANCEL_XML_UNAVAILABLECancellation XML unavailable: not yet cancelled, or not stored locally and could not be fetched from the platformFetch it after the cancellation success event; if it could not be fetched, retry later
10029844ENGINE_EXPORT_FAILEDWriting the export or backup file failed: the destination is not writable, or the backup file already existsUse another directory or file name; check disk space and permissions
10029845ENGINE_SUBSTITUTE_KEY_INVALIDThe substitute document key for cancellation by substitution is invalid, or is not a non-rejected offline document of this company on this deviceSend the 44-digit key of the offline document this device issued for the same sale
10029846ENGINE_BACKUP_INVALIDThe 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 400Check the backup passphrase; use an intact backup. The original database stays unchanged
10029874ENGINE_PARAMS_INVALIDParameter missing or of the wrong type; Detalhes.campo names the parameterFix the parameter, for example a request that is not a JSON object, the certificate thumbprint format or the date format
10029877ENGINE_RUNTIME_NOT_FOUNDRuntime not foundCheck the installer and the runtime directory
10029878ENGINE_TOO_MANY_PENDINGMore than 64 calls waiting at the same timeReduce concurrency
10029880ENGINE_PRINCIPAL_UNREACHABLEA secondary in primary/secondary mode cannot reach the primary; the request did not get thereRetry later, or move the till to the backup machine
10029881ENGINE_PRINCIPAL_RESULT_UNKNOWNThe request reached the primary but no response came back; the result is unknownAfter the primary recovers, query with the same id; reissuing with the same id and content does not issue twice
10029882ENGINE_TERMINAL_TOKEN_INVALIDThe terminal token of the secondary is invalid or revokedIssue a new terminal token on the primary and update the secondary configuration
10029883ENGINE_PRINCIPAL_ADDRESS_INVALIDThe primary address is badly formatted or not a private local network addressFix the primary address in the secondary configuration
10029884ENGINE_MODE_METHOD_UNAVAILABLEThe current mode does not offer this methodPairing, certificate change, backup and export run on the primary; terminal management is primary only
10029885ENGINE_PRINCIPAL_REJECTEDThe primary rejected the request source, for example a secondary outside the allowed networksCheck the primary's allowed networks and the network
10029886ENGINE_PRINCIPAL_RATE_LIMITEDToo many failed authentications; rate-limited by the primaryCheck the token and retry after 1 minute
10029887ENGINE_PRINCIPAL_LISTEN_FAILEDThe local network port of the primary cannot be openedChange the primary port or free the port
10029888ENGINE_TERMINAL_NOT_FOUNDThe terminal to revoke does not existCheck the terminal identifier

Invoice Assistant

CodeHTTPScenarioAction
10029900401Cashier token missingSend Authorization: Bearer tfl_…
10029901401Cashier token invalid or revokedThe store manager generates a new token
10029902403The token has no access to this companyGenerate a token that includes the company
10029903403Source address outside the allowed local network rangesCheck the local network mode settings
10029904400Invalid callback URLOnly http / https; with local network mode off, only loopback addresses
10029905401Desktop program action requires a manager sessionLog in with the manager PIN
10029906401Wrong manager PINType it again; 5 wrong attempts in total lock it
10029907409Printer unavailableCheck the printer connection and the printer chosen in Settings
10029908409Setup wizard not finishedFinish the setup wizard first
10029909400Invalid requestFix as described in mensagem
10029910404Resource not foundCheck the path
10029911400Invalid PIN format; it must be 6 to 8 digitsSet it again in that format
10029912500Internal assistant errorExport the diagnostics package and contact the platform
10029913403Host header of a desktop program request not allowed; only 127.0.0.1, localhost or [::1] plus the assistant port are acceptedOpen the desktop program at http://127.0.0.1:port, not through a proxy or another host name
10029914429Too many wrong PIN attempts; lockedWait for the lock to end, see the Invoice Assistant FAQ
10029916409Chosen port is taken or cannot be listened on; settings unchangedChoose another port
10029917403Cashier session has no access to this companyLog in with the manager PIN to do it
10029918429Assistant busy: 3 XML fetches are already in progress, or an export or backup is already in progressRetry later; do not repeat the call in quick succession
10029919400Invalid outbound proxy settingsCorrect "Internet connection" and "Address" of the outbound proxy in the desktop program's "Settings" as prompted; the settings were not saved
10029920409Saving 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 secondsWait for those operations to finish, then save or restore again; neither the settings nor the local database were changed
10029922409Less than 256 MB free on the disk holding the assistant's data directory; the export, backup or backup file upload was refusedFree up space on that disk and retry
10029923403A desktop program request has a missing or wrong anti-forgery token, usually because the session expired or the page was left open too longRefresh the page; if it persists, sign in again with the manager PIN
10029924429Cashier sessions opened too often; at most 20 per minute from the same originWait 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.

codigoHTTPScenarioAction
10017002 / 10017003404cteId not found or not owned by the companyCheck id and empresaId
10003000404empresaId not foundCheck empresaId
10017004400Company cannot issue (not approved / certificate not ready)Wait for approval / link the certificate
10017005 / 10017006400Concurrent duplicate request / too many pending tasks for the CNPJRetry later
10017007400Number series unresolved (none configured, or several enabled without a choice)Configure a model 57 series
10017010400ambienteEmissao differs from the company's environmentSubmit for the company's environment
10017011400Municipality IBGE code not foundCheck codigoIbge
10017050400codigoIbge missing and it could not be filled from the CEP: cep absent, not in the reference data, or maps to more than one municipalitySend codigoIbge or check cep
10017012 / 10017013400Party missing / taker inconsistent with the IE indicatorAdd the party or change indicadorIeTomador
10017014400Invalid document references (missing, bad check digit, mixed groups, previous documents inconsistent with the service type)Adjust the references
10017015400Document type inconsistent with references (complementary / substitute)Send ctesComplementados / cteSubstituido per tipo
10017016400Components do not sum to the total, or aReceber above the totalFix the amounts
10017017 / 10017018 / 10017019400Invalid RNTRC / unsupported modal / invalid enum or format (mensagem names the field)Fix per mensagem
10017020 to 10017025400Tax parameter missing / not allowed / regime mismatch / icmsUfFim required / rate table row missing / unsupported CSTSee the tax parameters in CT-e
10017030400Same id with a different messageUse a new id or resend the original message
10017031400Production: an active / authorized document already exists for the idQuery the original
10017040 to 10017045400Status does not allow the event / cancellation window exceeded / invalid event text / SEFAZ rejected the event / correction sequence limit / referenced event not foundSee the cancellation and event rules in CT-e
10017048 / 10017049400Cancellation blocked by a registered correction letter / correction letter outside the 720-hour windowSee the cancellation and event rules in CT-e
10001001400Request 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.

codigoHTTPScenarioAction
10019002 / 10019003404dceId not found, not owned by the company, or cancellation requested before the document was materializedCheck id and empresaId; cancel Pendente documents only after authorization
10003000404empresaId not foundCheck empresaId
10019012 / 10019010400Company not configured for DC-e (missing tipoEmitente / model 99 series / Marketplace site), or ambiente differs from the company's current environmentSend emissaoDCe at registration or through an update with id; submit for the company's current environment and ask operations for the production switch
10019014400Marketplace / Carrier company without remetenteAdd the sender
10019015400remetente.endereco missingAdd the sender address
10019016400Brazilian sender without cpfCnpjAdd the sender document
10019004400Company cannot issue (not approved / certificate not ready)Wait for approval / link the certificate
10019017400Brazilian recipient without cpfCnpjAdd the recipient document
10019011400Municipality IBGE code not found or inconsistent with ufCheck cidade / uf
10019049400IBGE 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 stateSend the IBGE code or check cep / uf
10019005 / 10019006400Concurrent duplicate request / too many pending tasks for the CNPJRetry later
10019007400Number series unresolved (several enabled series)Ask operations to consolidate the series
10019013400Issuer type Carrier not supported for issuance yetUse a Marketplace / OwnIssuer company
10019018400Invalid item (NCM length, quantity ≤ 0, negative unit price)Fix per mensagem
10019019400Invalid enum or format (mensagem names the field: tipoPessoa, modalidade, dataEmissao, documents, phone, e-mail, own-issuer remetente differing from the company)Fix per mensagem
10019020400Invalid carrier CNPJFix cnpjTransportadora
10019021400Additional information too longShorten the text
10019022400Invalid autorizacaoDownloadXml count or document; contains the issuer's own CNPJ; duplicate documentFix the list
10019030400Same id with a different messageUse a new id or resend the original message
10019031400Production: an active / authorized document already exists for the idQuery the original
10019040 to 10019043400Status does not allow cancellation / 24-hour window exceeded / cancellation already accepted / invalid reasonSee the cancellation rules in DC-e
10019048400dataEmissao 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
10001001400Request field validation failed (one entry per field); registration / update contract errors of emissaoDCeFix 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.

codigoHTTPScenarioWhat to do
10018001400Parameter 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 / 10018003404Document not found: nfseId does not belong to this issuer, or the inbound key is not among its received invoicesCheck nfseId / chaveAcesso against empresaId
10018004400Issuer not eligible (disabled / certificate unusable)Check issuer status and certificate
10018005400Issuer has no NFS-e profile; mensagem names the missing itemSend emissaoNFSe at registration or update with id
10018010400The municipality's NFS-e standard is not supported yetThat municipality cannot issue yet, contact the platform
10018012400Service code is not in the official LC 116 listCheck codigoTributacaoNacional
10018013400Recipient document is invalidCheck the CPF / CNPJ / NIF
10018014400Service export is missing the destination countryAdd servico.paisPrestacao
10018015400The replaced document cannot be replacedCheck the status of the replaced document
10018020400ISS rate could not be resolved (no inline value or municipal parameter)Send servico.iss.aliquota or the right servico.codigoTributacaoMunicipal
10018022400A Simples issuer must not send the ISS rate directlyRemove aliquota
10018023400Federal 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/cofinsProvide 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 / 10018031400The same request is already being processed / that order already has an invoice or the same id carries different contentRetry later; use another order number or check the content
10018040400A cancellation review is already in progressWait for the municipal verdict
10018041400The document has already been replacedNo further operation is allowed
10018042400The 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
10018063400The DPS message does not comply with the official XSD; details carry line, column, error key and element nameUsually text outside Latin-1, an incomplete address, or a value outside the official code table
10018064400The NFS-e event message does not comply with the official XSDCheck motivo length (15-255), the codigoMotivo value and the character set
10018065400The 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 acceptanceSend 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
10018066400IBGE 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 stateSend 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.

CodeHTTPCaseAction
10003000404empresaId not foundCheck empresaId
10021001404E-mail template not found or not owned by the integratorCheck templateId
10021002400Template disabled, or its document type differs from the documentUse another template or enable it
10021003400Template uses a variable outside the allow-listFix per the variable enumeration
10021004400Template HTML has forbidden content or the body exceeds 64 KBFix at the places the message names
10021005400Unsupported tipoDocumento in the template listSend only NFe / NFSe / CTe / DCe
10021010404Document not found or not owned by the companyCheck documentoId, tipoDocumento and empresaId
10021011400Document not authorized yet, or cancelled or replacedSend after authorization
10021012400No default template for this document typeSend templateId or set a default template
10021013400No recipientSend destinatarios
10021015409The previous e-mail for this document is not final yetWait for Enviado or Falha, then resend with a new id
10021020404E-mail not found or not owned by the companyCheck emailId and empresaId
10001001400Request 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:

codeEndpointMeaningAction
10015000XML verificationEmpty request bodySend the XML in the body
10015001XML verificationBody exceeds 1 MBAn authentic single NF-e never exceeds this; check that you are not wrapping or double-encoding
10015002XML verificationDTD detected (<!DOCTYPE)Strip DTDs
10015003XML verificationEncoding is not UTF-8Convert to UTF-8 before submitting
10015005XML verificationRetired, no longer returned (formerly: chave already submitted for verification by another integrator)No action needed: each integrator can verify the same invoice independently
10015104Chave lookupMalformed chave (length / characters / check digit)Validate locally first: 44 digits; the last digit is a mod-11 check digit
10015004Chave lookupInvoice not found in any sourceThe 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.

codeHTTPMeaningAction
10015104400Malformed chave (length / characters / check digit)Validate locally first: 44 digits; the last digit is a mod-11 check digit
10015300404Your 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
10015301409Verification not finished yet (PENDING_SEFAZ / VALIDATING)Fetch after receiving invoice.verify.completed
10015302409The current verdict produces no PDF (only VALIDATED and invoices with status Cancelada do)Do not retry
10015303409The platform is missing the original XML of this invoiceResubmit the same XML unchanged through XML verification, without forceRevalidate, then fetch again
10015304503The original XML is still being archivedRetry after Retry-After (5 seconds)
10015305503Generation is busy or temporarily unavailableRetry after Retry-After
10001000500Internal platform errorRetry 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[].codeNumericMeaning
XML_MALFORMED10015100XML syntax invalid
XSD_INVALID10015101Does not conform to the NF-e 4.00 XSD layout
SIGNATURE_INVALID10015102Digital signature verification failed (content tampered, or certificate expired at signing time)
SIGNATURE_CERT_MISMATCH10015103Signing certificate CNPJ does not match the issuer
ACCESS_KEY_INVALID10015104chave structure / check digit invalid
ACCESS_KEY_MISMATCH10015105chave segments do not match the document fields
PROTOCOL_MISMATCH10015106Protocol block inconsistent with the document
PROTOCOL_MISSING10015107No protocol node (warning, non-blocking)
XML_VERSION_UNSUPPORTED10015108Layout version is not 4.00

Tier-2 outcomes

Not HTTP errors: they arrive through the invoice.verify.completed webhook.

validationStatusTerminalAction
VALIDATEDYesSafe to proceed (release goods, settle)
REJECTEDYesDo not proceed; reason explains the SEFAZ verdict (cancelled / denied / voided / not found / protocol mismatch)
VALIDATION_ERROR (status null)Yes, retryablePlatform-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 itSEFAZ 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.

codeHTTPResponsible partyMeaningAction
10016000400CallerInvalid CPF format (11 digits required)Check for stray formatting characters or wrong length
10016001400CallerInvalid CPF check digitsValidate locally with the mod-11 algorithm first
10016002400CallerInvalid date of birth (valid DDMMYYYY required)Note the day-month-year order, and that the date must actually exist
10016003400CallerCPF not foundThe CPF does not exist, or the CPF and date of birth do not match (deliberately indistinguishable)
10016004451Third party (lawful upstream block)LGPD: menor de 16 anos (Lei Felca), holder is under 16Data lawfully withheld; do not retry
10016005422Third party (lawful upstream block)LGPD: menor de idade, holder is 16 to 17Data lawfully withheld; do not retry
10016006428Third party (lawful upstream block)LGPD: idade nao verificavel - informe a data de nascimento para completar a verificacao, age cannot be verifiedThe platform already re-verified once with the date of birth; do not retry
10016010400CallerInvalid CNPJ format (14 digits required)Check for stray formatting characters
10016011400CallerInvalid CNPJ check digitsValidate locally with the mod-11 algorithm first
10016012400CallerCNPJ not foundNo such CNPJ in the official registry
10016020503Third party (upstream unavailable)Upstream data source is temporarily unavailableRetry 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 timestamp and path.
  • Envelope errorType: 1 API error, 2 SEFAZ rejection, 3 system fault (retryable), 4 field validation failure (fix the request).
  • Never retry a rejected document blindly: Negada and REJECTED are terminal verdicts; act on the SEFAZ reason first.