Error Codes

Errors come in three shapes depending on which layer produced them — see General Conventions:

Layer	HTTP	Shape	Code field
Platform gateway (authentication, quota, retirement)	401 / 403 / 410 / 429	Platform envelope `{success, errorType, code, message}`	`code` (integer)
Issuance endpoints	400 / 404	Array `[{codigo, mensagem}]`	`codigo` (string)
Verification and identity endpoints	400	Bare object `{code, message}`	`code` (integer)

Messages are localized by the Language / Accept-Language headers (default Portuguese). Branch on codes, never on message text.

Code ranges by domain:

Range	Domain
10001xxx	Request field validation
10003xxx	Company and certificate
10004xxx	NF-e issuance and cancellation
10005xxx	Tax engine
10009xxx	Open platform (authentication, quota, webhooks, retirement)
10015xxx	NF-e verification
10016xxx	Identity lookup (CNPJ / CPF)

Gateway — authentication and authorization

Platform envelope shape. 401 and 403 are configuration errors — retrying without a fix is pointless and may trip rate limits; 429 is retryable with exponential backoff.

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 Troubleshooting
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
410	10009034	Endpoint retired; `message` names the replacement	Switch to the replacement — see Deprecated Endpoints; do not retry
429	10009006	Rate limit exceeded	Back off and retry (start at 1 s, double up to 30 s, add jitter); limits are per application and per endpoint group

Issuance — business and request-level errors

Array shape [{codigo, mensagem}]. codigo is a string: GW001, CER0005 and NFe0001 keep their alphanumeric values; all others are the platform error code as a numeric string. Request-body validation failures produce one entry per field.

codigo	HTTP	Scenario	Action
`GW001`	400	Registration: city / state cannot be resolved to an IBGE code; issuance: customer IBGE municipality code does not exist	Check the UF and city name / IBGE code
`CER0005`	400	Certificate password mismatch	Check the password
`NFe0001`	404	The `nfeId` for query / cancellation does not exist	Check the id sent at issuance and the `empresaId`
10001001	400	Request field validation failed (one entry per field)	Fix per `mensagem`
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
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: 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
10004030	400	`ambienteEmissao` does not match the company’s current environment	Submit under the company environment or ask operations to switch it
10004031	400	Value not supported in this phase (`presencaConsumidor` / multiple payments / unknown payment type / `tipoPessoa` inconsistent with the document)	Adjust to the supported range — see Issuance API
10005000	400	Insufficient tax parameters (e.g. a tax code that needs a rate)	See Tax codes and rates
10009033	400	Invalid webhook registration (id mismatch / non-JSON `contentType`)	Fix as described

Verification — request-level errors

Bare shape {code, message}, HTTP 400. The request never enters validation.

code	Endpoint	Meaning	Action
10015000	XML	Empty request body	Send the XML in the body
10015001	XML	Body exceeds 1 MB	An authentic single NF-e never exceeds this; check that you are not wrapping or double-encoding
10015002	XML	DTD detected (`<!DOCTYPE`)	Strip DTDs; they are rejected as an XXE safeguard
10015003	XML	Encoding is not UTF-8	Convert to UTF-8 before submitting
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
10015104	chave lookup	Malformed chave (length / characters / check digit)	Validate locally first: 44 digits; the last digit is a mod-11 check digit

Verification — 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 (VALIDATED / REJECTED / VALIDATION_ERROR) are not error codes; they arrive via webhook — see Verification API.

Identity — business errors

Bare shape {code, message}, HTTP 400. Format and check-digit errors are rejected locally and never reach the upstream source — they consume no quota and are not billed.

code	Meaning	Action
10016000	Invalid CPF format (11 digits required)	Check for stray formatting characters or wrong length
10016001	Invalid CPF check digits	Validate locally with the mod-11 algorithm first
10016002	Invalid date of birth (valid DDMMYYYY required)	Note the day-month-year order, and that the date must actually exist
10016003	CPF not found	The CPF does not exist, or the CPF and date of birth do not match (deliberately indistinguishable); also returned for protected subjects such as minors
10016010	Invalid CNPJ format (14 digits required)	Check for stray formatting characters
10016011	Invalid CNPJ check digits	Validate locally with the mod-11 algorithm first
10016012	CNPJ not found	No such CNPJ in the official registry

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: 10004002 (retry later).
410 — the endpoint is retired; switch to the replacement named in message.
429 — back off with exponential delay and jitter.
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).