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).

JSON
{
  "success": false,
  "error": {
    "code": "INVALID_API_CREDENTIALS",
    "message": "Credenciais de API inválidas.",
    "details": null
  }
}

Códigos HTTP e de negócio

HTTPcodeDescrição
400MISSING_API_KEYHeader X-Api-Key ausente
400MISSING_API_SECRETHeader X-Api-Secret ausente
400MISSING_COMPANY_IDcompanyId ausente no path
400INVALID_COMPANY_IDcompanyId do path não é UUID válido (ex.: CNPJ no lugar do ID). Liste em GET /v1/companies
401INVALID_API_CREDENTIALSChave ou secret inválidos
402SUBSCRIPTION_REQUIREDAssinatura em atraso ou suspensa
402ACCOUNT_SUBSCRIPTION_REQUIREDAssinatura da conta não encontrada
402FREE_PLAN_LIMIT_REACHEDLimite de emissões do plano gratuito atingido
403COMPANY_ACCESS_DENIEDUsuário sem acesso à empresa do path
403COMPANY_ARCHIVEDEmpresa desativada — não pode ser usada pela API
404COMPANY_NOT_FOUNDEmpresa não encontrada nesta conta/ambiente. Confira o id em GET /v1/companies (sandbox e produção têm IDs diferentes)
404INVOICE_NOT_FOUNDNota fiscal não encontrada
409COMPANY_ALREADY_EXISTSCNPJ já cadastrado nesta conta
422VALIDATION_ERRORCorpo da requisição inválido (Zod)
422INVALID_INVOICE_STATUSOperação não permitida para este status
429RATE_LIMIT_EXCEEDEDLimite 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

HTTPcodeDescrição
422NFSE_CERTIFICATE_MISSINGNFS-e: certificado A1 ausente (município exige certificado)
422NFSE_PREFECTURE_CREDENTIALS_MISSINGNFS-e: login/senha/token da prefeitura não configurados
422NFE_CERTIFICATE_MISSINGNF-e: certificado A1 ausente
422NFCE_CERTIFICATE_MISSINGNFC-e: certificado A1 ausente
422NFCE_CSC_MISSINGNFC-e: cscId/csc não configurados
422CTE_CERTIFICATE_MISSINGCT-e: certificado A1 ausente
422MDFE_CERTIFICATE_MISSINGMDF-e: certificado A1 ausente
403CTE_NOT_ENABLEDCT-e não liberado para esta empresa
403MDFE_NOT_ENABLEDMDF-e não liberado para esta empresa
422CTE_INACTIVECT-e desativado na empresa. Ative em PATCH /cte/settings
422MDFE_INACTIVEMDF-e desativado na empresa. Ative em PATCH /mdfe/settings

Emissão, edição e reprocessamento

HTTPcodeDescrição
400CTE_EXTERNAL_ID_REQUIREDCT-e / CT-e OS sem Idempotency-Key nem externalId
400MDFE_EXTERNAL_ID_REQUIREDMDF-e sem Idempotency-Key nem externalId
422CTE_TAKER_PARTY_REQUIREDTomador (takerParty) obrigatório (CT-e com taker 4; CT-e OS exceto bagagem)
400INVOICE_CANNOT_EMITPOST .../invoices/{id}/emit em nota que não pode ser emitida
409FISCAL_MODULE_INACTIVEPOST .../invoices/{id}/emit com o módulo fiscal do tipo desativado
409INVOICE_NOT_EDITABLEPATCH em nota autorizada ou cancelada
409INVOICE_VERSION_CONFLICTPATCH com version desatualizada

Cancelamento de NFS-e / NF-e / NFC-e (DELETE tipado — 202)

HTTPcodeDescrição
422INVALID_INVOICE_STATUSNota não está autorizada
422NFSE_PROVIDER_ID_MISSINGNFS-e sem identificador no emissor fiscal
422NFE_ACCESS_KEY_MISSINGNF-e sem chave de acesso
422NFCE_ACCESS_KEY_MISSINGNFC-e sem chave de acesso
409NFE_CANCEL_NOT_ALLOWEDNF-e fora do prazo de cancelamento ou bloqueada por regra fiscal
502CANCEL_ENQUEUE_FAILEDFalha ao enfileirar o cancelamento — tente novamente

Cancelamento via POST .../invoices/{id}/cancel (200)

HTTPcodeDescrição
409INVOICE_ALREADY_CANCELLEDNota já cancelada ou com cancelamento em andamento
409INVOICE_CANNOT_BE_CANCELLEDNota não autorizada ou em processamento
409NFE_CANCEL_NOT_ALLOWEDNF-e fora do prazo de cancelamento ou bloqueada por regra fiscal
409INVOICE_INTEGRATION_ID_MISSINGNota sem identificador no emissor fiscal
503CANCEL_TASK_ENQUEUE_FAILEDFalha ao agendar o cancelamento — tente novamente

Carta de correção (CC-e)

HTTPcodeDescrição
400INVOICE_TYPE_NOT_NFECC-e só existe para NF-e
409INVOICE_NOT_AUTHORIZEDNF-e não está autorizada
409NFE_CORRECTION_NOT_ALLOWEDPrazo ou regra fiscal não permite nova CC-e
422NFE_CORRECTION_INVALIDTexto/sequência da correção inválidos
422NFE_CORRECTION_REJECTEDSEFAZ recusou a CC-e

Inutilização de numeração

HTTPcodeDescrição
422NFE_INUTILIZATION_REJECTEDSEFAZ recusou a inutilização de NF-e (fica no histórico com confirmed: false)
422NFCE_INUTILIZATION_REJECTEDSEFAZ recusou a inutilização de NFC-e (fica no histórico com confirmed: false)

CT-e e MDF-e

HTTPcodeDescrição
404CTE_NOT_FOUNDCT-e não encontrado
404MDFE_NOT_FOUNDMDF-e não encontrado
422CTE_NOT_CANCELLABLESó CT-e autorizado pode ser cancelado
422MDFE_NOT_CANCELLABLESó MDF-e autorizado pode ser cancelado
422MDFE_NOT_CLOSABLESó MDF-e autorizado pode ser encerrado
422MDFE_NOT_EVENTABLECondutor/documento/pagamento só em MDF-e autorizado
422CTE_ACCESS_KEY_MISSINGConsulta de CT-e sem chave de acesso
422MDFE_ACCESS_KEY_MISSINGConsulta de MDF-e sem chave de acesso
503CTE_CANCEL_QUEUE_FAILEDFalha ao enfileirar o cancelamento do CT-e
503MDFE_CANCEL_QUEUE_FAILEDFalha ao enfileirar o cancelamento do MDF-e
503MDFE_EVENT_QUEUE_FAILEDFalha ao enfileirar encerramento/evento do MDF-e

Arquivos, consulta e e-mail

HTTPcodeDescrição
400INVOICE_ASSETS_UNAVAILABLEPDF/XML só existem após autorização (ou cancelamento confirmado)
400NFCE_CONSULT_UNSUPPORTEDGET .../invoices/{id}/consult não reconsulta NFC-e
400INVOICE_TYPE_NOT_SUPPORTEDsend-borrower-email só para NFS-e e NF-e
400INVOICE_NOT_AUTHORIZEDsend-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.

JSON
{
  "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."
        }
      ]
    }
  }
}