Referência

Códigos de Resposta HTTP

Referência dos códigos de status retornados pela API. Use essa página para tratar respostas corretamente na sua integração.

Visão geral#

Código	Status	Categoria	Descrição
`200`	OK	Sucesso	Requisição processada com sucesso. Retornado pelo registro de webhooks.
`202`	Accepted	Sucesso	Consulta de score aceita e em processamento. O resultado será entregue via webhook.
`400`	Bad Request	Erro do cliente	O corpo da requisição é inválido. Verifique os campos obrigatórios e seus formatos.
`401`	Unauthorized	Erro do cliente	Chave de API ausente, inválida ou expirada. Verifique o header Authorization.
`428`	Precondition Required	Erro do cliente	Nenhum webhook registrado para o ambiente. Registre um webhook antes de enviar consultas.
`500`	Internal Server Error	Erro do servidor	Erro inesperado no servidor. Tente novamente. Se persistir, entre em contato com o suporte.

Detalhamento#

200 OK#

Retornado quando o webhook é registrado ou atualizado com sucesso via POST /v1/webhooks.

202 Accepted#

A consulta de score foi aceita e está sendo processada. A resposta inclui um request_id para rastreio. O resultado será entregue via webhook.

json

{
  "request_id": "req_8f2b4a2d...",
  "status": "processing",
  "received_at": "2026-03-07T12:00:00Z"
}

400 Bad Request#

O corpo da requisição contém dados inválidos. A mensagem de erro indica o campo e o problema específico.

json

{
  "error": "Invalid document_type. Use cpf or cnpj."
}

Veja as validações detalhadas nas páginas de consulta de score e webhooks.

401 Unauthorized#

A chave de API não foi encontrada, é inválida ou está expirada. Verifique o header Authorization e consulte a seção de autenticação.

json

{
  "error": "Invalid or missing API key."
}

428 Precondition Required#

Retornado pelo endpoint POST /v1/score quando não há webhook registrado para o ambiente. Registre um webhook primeiro via POST /v1/webhooks.

json

{
  "error": "No webhook is registered for this environment."
}

500 Internal Server Error#

Um erro inesperado ocorreu. Aguarde alguns segundos e tente novamente. Se o erro persistir, entre em contato pelo suporte.

Formato padrão de erro#

Todas as respostas de erro seguem o mesmo formato, com um campo error contendo uma mensagem descritiva em inglês:

json

{
  "error": "Descriptive error message."
}

Tratamento de erros

Sempre verifique o status HTTP antes de processar o corpo da resposta. Use a mensagem do campo error para debugging — não exiba diretamente para o usuário final.