Códigos HTTP das respostas

Nossas APIs utilizam respostas HTTP convencionais para indicar sucesso ou falha nas requisições. Respostas com status 2xx indicam sucesso, status 4xx indicam falhas decorrentes de erros nas informações enviadas, e status 5xx indicam falhas decorrentes de problemas internos ou de infraestrutura.

TIP

A tabela a seguir lista os códigos de resposta HTTP utilizados em nossas APIs:

Código HTTP	Descrição
200 OK	Sua requisição foi processada com sucesso.
201 Created	A requisição foi bem-sucedida e um recurso foi criado como resultado.
400 Bad Request	É retornado apenas por rotas administrativas internas, fora do escopo desta documentação. No uso normal das APIs, você não recebe este código.
401 Unauthorized	A chave de API está ausente, é inválida ou não tem permissão para o recurso solicitado.
404 Not Found	O endpoint ou o objeto solicitado não existe.
413 Payload Too Large	Um arquivo enviado em multipart/form-data excede o tamanho máximo aceito. Consulte os valores em Limites.
415 Unsupported Media Type	O header Content-Type da requisição está ausente ou não é suportado. Este código não trata do formato do arquivo enviado, que é validado com o código 422.
422 Unprocessable Entity	É o erro mais comum das nossas APIs. Ocorre quando falta um parâmetro obrigatório, quando o valor enviado é inválido (por exemplo, um CPF que não passa na validação do dígito verificador), quando o formato do arquivo não é aceito ou quando são enviados arquivos em excesso. A mensagem da resposta indica qual é o caso.
500 Internal Server Error	Ocorreu uma falha inesperada em nossos servidores. Por segurança, os detalhes são ofuscados.

🚧 Atenção!

O código 200 não significa um resultado positivo, por exemplo, que encontramos um documento na classificação, significa apenas que a análise ocorreu com sucesso sem erros internos. Para identificar quais informações foi possível extrair, observe diretamente o campo equivalente no objeto de resposta da requisição.

Formato das respostas de erro

Os erros gerados pela aplicação seguem o formato abaixo:

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "error": {
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "message": "Invalid Federal Revenue Number"
  }
}

Campo	Descrição	Tipo
id	Identificador único da requisição. Informe-o ao acionar o suporte.	String
error.statusCode	O mesmo código HTTP da resposta.	Number
error.error	Nome do erro HTTP.	String
error.message	Descrição do que impediu o processamento.	String

WARNING

Erros tratados pela infraestrutura, e não pela aplicação, podem chegar em outro formato e sem o id no corpo. É o caso de uma rota inexistente e de um corpo de requisição acima do limite aceito, recusado antes de o identificador ser gerado. Nesses casos, o identificador da requisição está no header Nextid-ReqId, presente em todas as respostas.

TIP

O id é a forma mais rápida de investigarmos um caso específico. Guarde-o nos seus logs.

Tarifação

O código HTTP da resposta determina se a requisição gera cobrança. Veja Tarifação das APIs.