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 malformadaCorrija o JSON ou os cabeçalhos
- 401Não autenticadoConfira a chave e o ambiente
- 403Sem permissãoRevise escopos, empresas e IPs liberados para a chave
- 404Não encontradoConfira o id e se o recurso é do mesmo ambiente da chave
- 409ConflitoA operação já foi feita ou o estado da nota não permite a ação
- 422Dados inválidosCorrija os campos apontados em detalhes
- 429Limite excedidoEspere o tempo indicado em Retry-After
- 5xxFalha do nosso ladoRepita com a mesma Idempotency-Key
Objeto de erro
{ "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" }}codigostringIdentificador estável do erro. Use este campo, e não a mensagem, na lógica do seu sistema.
mensagemstringExplicação em português. Pode mudar sem aviso.
detalhesarraysó em 422Presente em erros 422. Lista o campo e o problema de cada dado recusado.
requisicao_idstringIdentificador 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_invalidaA chave não existe, foi revogada ou é de outro ambiente.
- 403empresa_nao_autorizadaA chave não tem acesso à empresa informada.
- 403ip_nao_autorizadoA chamada veio de um IP fora da lista liberada para a chave.
- 409idempotencia_em_conflitoA mesma Idempotency-Key chegou com outro corpo.
- 422dados_invalidosHá campos inválidos. O campo detalhes aponta cada um.
- 429limite_excedidoA 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 422Não. Corrija a requisição antes
- 409Não. Consulte o estado atual do recurso
- 429Sim, depois do tempo em Retry-After
- 5xx ou sem respostaSim, com a mesma Idempotency-Key
Falando com o suporte
Mande o requisicao_id da resposta. Com ele localizamos a chamada nos nossos registros.