Erros
Todos os erros seguem o mesmo formato JSON. O campo code é estável e pode ser tratado programaticamente; message é legível por humanos (PT-BR).
{
"success": false,
"error": {
"code": "INVALID_API_CREDENTIALS",
"message": "Credenciais de API inválidas.",
"details": null
}
}
Códigos HTTP e de negócio
| HTTP | code | Descrição |
|---|
400 | MISSING_API_KEY | Header X-Api-Key ausente |
400 | MISSING_API_SECRET | Header X-Api-Secret ausente |
400 | MISSING_COMPANY_ID | companyId ausente no path |
400 | INVALID_COMPANY_ID | companyId do path não é UUID válido (ex.: CNPJ no lugar do ID). Liste em GET /v1/companies |
401 | INVALID_API_CREDENTIALS | Chave ou secret inválidos |
402 | SUBSCRIPTION_REQUIRED | Assinatura em atraso ou suspensa |
402 | ACCOUNT_SUBSCRIPTION_REQUIRED | Assinatura da conta não encontrada |
402 | FREE_PLAN_LIMIT_REACHED | Limite de emissões do plano gratuito atingido |
403 | COMPANY_ACCESS_DENIED | Usuário sem acesso à empresa do path |
403 | COMPANY_ARCHIVED | Empresa desativada — não pode ser usada pela API |
404 | COMPANY_NOT_FOUND | Empresa não encontrada nesta conta/ambiente. Confira o id em GET /v1/companies (sandbox e produção têm IDs diferentes) |
404 | INVOICE_NOT_FOUND | Nota fiscal não encontrada |
409 | COMPANY_ALREADY_EXISTS | CNPJ já cadastrado nesta conta |
422 | VALIDATION_ERROR | Corpo da requisição inválido (Zod) |
422 | INVALID_INVOICE_STATUS | Operação não permitida para este status |
429 | RATE_LIMIT_EXCEEDED | Limite de requisições excedido (conforme o plano) |
Códigos por operação
Além dos códigos gerais acima, cada operação tem códigos próprios. O code é o contrato estável; trate pelo code, não pela mensagem.
Configuração da empresa para emitir
| HTTP | code | Descrição |
|---|
422 | NFSE_CERTIFICATE_MISSING | NFS-e: certificado A1 ausente (município exige certificado) |
422 | NFSE_PREFECTURE_CREDENTIALS_MISSING | NFS-e: login/senha/token da prefeitura não configurados |
422 | NFE_CERTIFICATE_MISSING | NF-e: certificado A1 ausente |
422 | NFCE_CERTIFICATE_MISSING | NFC-e: certificado A1 ausente |
422 | NFCE_CSC_MISSING | NFC-e: cscId/csc não configurados |
422 | CTE_CERTIFICATE_MISSING | CT-e: certificado A1 ausente |
422 | MDFE_CERTIFICATE_MISSING | MDF-e: certificado A1 ausente |
403 | CTE_NOT_ENABLED | CT-e não liberado para esta empresa |
403 | MDFE_NOT_ENABLED | MDF-e não liberado para esta empresa |
422 | CTE_INACTIVE | CT-e desativado na empresa. Ative em PATCH /cte/settings |
422 | MDFE_INACTIVE | MDF-e desativado na empresa. Ative em PATCH /mdfe/settings |
Emissão, edição e reprocessamento
| HTTP | code | Descrição |
|---|
400 | CTE_EXTERNAL_ID_REQUIRED | CT-e / CT-e OS sem Idempotency-Key nem externalId |
400 | MDFE_EXTERNAL_ID_REQUIRED | MDF-e sem Idempotency-Key nem externalId |
422 | CTE_TAKER_PARTY_REQUIRED | Tomador (takerParty) obrigatório (CT-e com taker 4; CT-e OS exceto bagagem) |
400 | INVOICE_CANNOT_EMIT | POST .../invoices/{id}/emit em nota que não pode ser emitida |
409 | FISCAL_MODULE_INACTIVE | POST .../invoices/{id}/emit com o módulo fiscal do tipo desativado |
409 | INVOICE_NOT_EDITABLE | PATCH em nota autorizada ou cancelada |
409 | INVOICE_VERSION_CONFLICT | PATCH com version desatualizada |
Cancelamento de NFS-e / NF-e / NFC-e (DELETE tipado — 202)
| HTTP | code | Descrição |
|---|
422 | INVALID_INVOICE_STATUS | Nota não está autorizada |
422 | NFSE_PROVIDER_ID_MISSING | NFS-e sem identificador no emissor fiscal |
422 | NFE_ACCESS_KEY_MISSING | NF-e sem chave de acesso |
422 | NFCE_ACCESS_KEY_MISSING | NFC-e sem chave de acesso |
409 | NFE_CANCEL_NOT_ALLOWED | NF-e fora do prazo de cancelamento ou bloqueada por regra fiscal |
502 | CANCEL_ENQUEUE_FAILED | Falha ao enfileirar o cancelamento — tente novamente |
Cancelamento via POST .../invoices/{id}/cancel (200)
| HTTP | code | Descrição |
|---|
409 | INVOICE_ALREADY_CANCELLED | Nota já cancelada ou com cancelamento em andamento |
409 | INVOICE_CANNOT_BE_CANCELLED | Nota não autorizada ou em processamento |
409 | NFE_CANCEL_NOT_ALLOWED | NF-e fora do prazo de cancelamento ou bloqueada por regra fiscal |
409 | INVOICE_INTEGRATION_ID_MISSING | Nota sem identificador no emissor fiscal |
503 | CANCEL_TASK_ENQUEUE_FAILED | Falha ao agendar o cancelamento — tente novamente |
Carta de correção (CC-e)
| HTTP | code | Descrição |
|---|
400 | INVOICE_TYPE_NOT_NFE | CC-e só existe para NF-e |
409 | INVOICE_NOT_AUTHORIZED | NF-e não está autorizada |
409 | NFE_CORRECTION_NOT_ALLOWED | Prazo ou regra fiscal não permite nova CC-e |
422 | NFE_CORRECTION_INVALID | Texto/sequência da correção inválidos |
422 | NFE_CORRECTION_REJECTED | SEFAZ recusou a CC-e |
Inutilização de numeração
| HTTP | code | Descrição |
|---|
422 | NFE_INUTILIZATION_REJECTED | SEFAZ recusou a inutilização de NF-e (fica no histórico com confirmed: false) |
422 | NFCE_INUTILIZATION_REJECTED | SEFAZ recusou a inutilização de NFC-e (fica no histórico com confirmed: false) |
CT-e e MDF-e
| HTTP | code | Descrição |
|---|
404 | CTE_NOT_FOUND | CT-e não encontrado |
404 | MDFE_NOT_FOUND | MDF-e não encontrado |
422 | CTE_NOT_CANCELLABLE | Só CT-e autorizado pode ser cancelado |
422 | MDFE_NOT_CANCELLABLE | Só MDF-e autorizado pode ser cancelado |
422 | MDFE_NOT_CLOSABLE | Só MDF-e autorizado pode ser encerrado |
422 | MDFE_NOT_EVENTABLE | Condutor/documento/pagamento só em MDF-e autorizado |
422 | CTE_ACCESS_KEY_MISSING | Consulta de CT-e sem chave de acesso |
422 | MDFE_ACCESS_KEY_MISSING | Consulta de MDF-e sem chave de acesso |
503 | CTE_CANCEL_QUEUE_FAILED | Falha ao enfileirar o cancelamento do CT-e |
503 | MDFE_CANCEL_QUEUE_FAILED | Falha ao enfileirar o cancelamento do MDF-e |
503 | MDFE_EVENT_QUEUE_FAILED | Falha ao enfileirar encerramento/evento do MDF-e |
Arquivos, consulta e e-mail
| HTTP | code | Descrição |
|---|
400 | INVOICE_ASSETS_UNAVAILABLE | PDF/XML só existem após autorização (ou cancelamento confirmado) |
400 | NFCE_CONSULT_UNSUPPORTED | GET .../invoices/{id}/consult não reconsulta NFC-e |
400 | INVOICE_TYPE_NOT_SUPPORTED | send-borrower-email só para NFS-e e NF-e |
400 | INVOICE_NOT_AUTHORIZED | send-borrower-email em nota não autorizada |
Erros de validação
Erros de validação do corpo da requisição (Zod) retornam 422 com code: VALIDATION_ERROR. Os campos inválidos ficam em error.details.fields.
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "É necessário informar o e-mail do tomador. Há mais 1 campo para corrigir (veja details.fields).",
"details": {
"fields": [
{
"field": "borrower.email",
"error": "É necessário informar o e-mail do tomador."
},
{
"field": "items.0.quantity",
"error": "A quantidade do item 1 deve ser maior que 0."
}
]
}
}
}