Tratamento de Erros

Como a API NFe/CTe Inbound sinaliza erros e como seu cliente deve reagir.

Sumário

• Formato do Erro
• Códigos HTTP
• Headers de Rate Limiting
• Estratégia de Retry

Formato do Erro

Na maior parte dos erros, a API retorna um JSON no seguinte formato:

{
  "errors": [
    {
      "message": "transportation invoice 35240198765432000100570010000009871234567890 not found for company comp_123"
    }
  ]
}

• message traz o texto específico do erro. Quando não há texto específico, vem a mensagem padrão do status: "bad request" (400), "forbidden" (403), "not found" (404), "conflict" (409), "expectation failed" (417), "unprocessable entity" (422) ou "service unavailable" (503). O item de erro não vem mais vazio ({"errors":[{}]}), como acontecia antes em alguns 404.
• code é opcional e, em geral, não vem no corpo. Use o status HTTP da resposta para decidir o tratamento, não um campo do corpo.
• Trate message como texto livre: ela serve para log e diagnóstico, não para parsing.

Exceções a esse formato:

• 500 e 504 podem vir sem corpo.
• Algumas rotas devolvem uma string simples em 400, sem o objeto errors.
• Erros de validação do modelo (corpo JSON malformado ou com tipo errado) respondem 400 no formato ProblemDetails (type, title, status, errors), gerado pelo ASP.NET Core.

Por isso, decida o tratamento pelo status HTTP e leia o corpo de forma tolerante.

Códigos HTTP

HTTP	Significa	O que fazer
200	Sucesso	Processe a resposta normalmente
204	Sucesso sem conteúdo	Operação realizada, sem corpo de resposta
400	Requisição inválida	Verifique os parâmetros enviados
401	Não autorizado	Verifique sua API Key ou token
403	Proibido	Sua conta não tem permissão para este recurso (API Key sem o papel exigido), ou a empresa não está com o inbound de NF-e ativo. Veja 403 com inbound de NF-e desativado
404	Não encontrado	O documento/empresa não existe
409	Conflito (duplicado)	Recurso já existe. Em POST .../manifestation-events (e no legado POST /manifest), significa que já existe um evento Pending ou Accepted para a mesma (accessKey, eventCode, nSequencia) — trate como idempotente
422	Entidade não processável	Dados válidos mas não processáveis. Ex.: GET .../inbound/{access_key}/pdf de um resumo de NF-e ou de um evento, que não têm DANFE (antes: 500). Não adianta repetir
503	Serviço indisponível	SEFAZ temporariamente fora. Tente novamente em alguns minutos
504	Timeout	A operação demorou muito. Tente novamente
500	Erro interno	Entre em contato com o suporte

403 com inbound de NF-e desativado

Quando a empresa não está com o inbound de NF-e ativo (nunca habilitado ou desativado), as leituras de NF-e respondem 403 com o corpo de erro padrão. Antes, esses casos respondiam 500.

• GET .../inbound/productinvoices/{access_key}, /json e /events/{event_key}
• GET .../inbound/{access_key}, /events/{event_key} e /pdf
• DELETE .../inbound/productinvoices repetido numa empresa já desativada

Exceção: GET .../inbound/{access_key}/xml segue respondendo 400 nesse caso. A API Key é válida; o que falta é a habilitação do serviço. Reative com POST .../inbound/productinvoices (veja Ativar via API).

{
  "errors": [
    {
      "message": "Company: 5f4d4cee0a8b8e2c3a1bcd11 não habilitada para o NFe Distribuição"
    }
  ]
}

Headers de Rate Limiting

Todas as respostas incluem headers indicando o status do rate limit:

Header	Descrição
X-RateLimit-Limit	Total de requisições permitidas por janela
X-RateLimit-Remaining	Requisições restantes na janela atual
X-RateLimit-Reset	Timestamp Unix quando a janela reinicia

Quando o limite é excedido, a API retorna 429 Too Many Requests. Aguarde até X-RateLimit-Reset antes de tentar novamente.

Estratégia de Retry

Para erros 429, 503 e 504, recomendamos retry com backoff exponencial:

import time
import requests

def get_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            reset_time = int(response.headers.get('X-RateLimit-Reset', time.time() + 60))
            wait_time = max(reset_time - time.time(), 1)
            time.sleep(wait_time)
            continue

        if response.status_code in (503, 504):
            wait_time = (2 ** attempt) * 1  # 1s, 2s, 4s
            time.sleep(wait_time)
            continue

        return response

    raise Exception("Max retries exceeded")

Veja também

• Tipos e enums
• Endpoints de NF-e
• Endpoints de CT-e
• Webhook events + HMAC
• FAQ