ConceitosErros

Erros

A API usa os códigos HTTP convencionais e devolve sempre o mesmo objeto de erro: um código estável para o seu sistema tratar e uma mensagem para quem está depurando.

Códigos HTTP

StatusSignificadoO que fazer

  • 400Requisição malformada
    Corrija o JSON ou os cabeçalhos
  • 401Não autenticado
    Confira a chave e o ambiente
  • 403Sem permissão
    Revise escopos, empresas e IPs liberados para a chave
  • 404Não encontrado
    Confira o id e se o recurso é do mesmo ambiente da chave
  • 409Conflito
    A operação já foi feita ou o estado da nota não permite a ação
  • 422Dados inválidos
    Corrija os campos apontados em detalhes
  • 429Limite excedido
    Espere o tempo indicado em Retry-After
  • 5xxFalha do nosso lado
    Repita com a mesma Idempotency-Key

Objeto de erro

422 Unprocessable Entity
{  "erro": {    "codigo": "dados_invalidos",    "mensagem": "Há campos inválidos na requisição.",    "detalhes": [      { "campo": "tomador.documento", "mensagem": "CNPJ com dígito verificador incorreto." },      { "campo": "servico.valor", "mensagem": "Deve ser maior que zero." }    ],    "requisicao_id": "req_7Hc2Lq9Vx1"  }}
codigostring
Identificador estável do erro. Use este campo, e não a mensagem, na lógica do seu sistema.
mensagemstring
Explicação em português. Pode mudar sem aviso.
detalhesarraysó em 422
Presente em erros 422. Lista o campo e o problema de cada dado recusado.
requisicao_idstring
Identificador da chamada. Informe ao suporte para localizarmos o registro.

Códigos de erro comuns

O campo codigo é estável e pode ser usado na lógica do seu sistema. Estes aparecem em qualquer endpoint. Os específicos de cada recurso estão na referência.

StatusCódigoQuando acontece

  • 401chave_invalida
    A chave não existe, foi revogada ou é de outro ambiente.
  • 403empresa_nao_autorizada
    A chave não tem acesso à empresa informada.
  • 403ip_nao_autorizado
    A chamada veio de um IP fora da lista liberada para a chave.
  • 409idempotencia_em_conflito
    A mesma Idempotency-Key chegou com outro corpo.
  • 422dados_invalidos
    Há campos inválidos. O campo detalhes aponta cada um.
  • 429limite_excedido
    A chave passou do limite de requisições por minuto.

Repetindo com segurança

Em falha de rede, 429 ou 5xx, repita com espera crescente: 1 s, 2 s, 4 s e assim por diante. Nas operações de escrita, mande sempre a mesma Idempotency-Key. Se a primeira tentativa já tiver sido processada, a API devolve o resultado original em vez de emitir outra nota.

RespostaRepetir?

  • 400 401 403 404 422
    Não. Corrija a requisição antes
  • 409
    Não. Consulte o estado atual do recurso
  • 429
    Sim, depois do tempo em Retry-After
  • 5xx ou sem resposta
    Sim, com a mesma Idempotency-Key

Falando com o suporte

Mande o requisicao_id da resposta. Com ele localizamos a chamada nos nossos registros.