Pular para o conteúdo principal

Tratamento de Erros

Entenda como a API Checktudo comunica erros e como tratá-los em sua aplicação.

Formato das Respostas​

Sucesso​

Toda resposta de sucesso vem dentro de um envelope:

{
"statusCode": 201,
"data": {
"queryId": "550e8400-e29b-41d4-a716-446655440000",
"status": "pendente"
}
}

Erro​

Todo erro segue o mesmo formato:

{
"statusCode": 409,
"timestamp": "2026-10-26T18:00:00.000Z",
"path": "/queries/integration/veiculo-total-mais",
"error": "DuplicateQueryError",
"message": "A consulta referida de Veículo Total +, foi executada recentemente. ...",
"data": {
"existingQueryId": "550e8400-e29b-41d4-a716-446655440000",
"existingQueryCreatedAt": "2026-10-26T17:40:00.000Z"
}
}
CampoDescrição
statusCodeCódigo HTTP
timestampMomento do erro (ISO-8601 UTC)
pathRota chamada
errorTipo do erro (ex.: NotFoundError, ConflictError)
messageDescrição do erro
dataPresente só em DuplicateQueryError, com a consulta já existente

Códigos de Status HTTP​

CódigoQuando acontece
200Resultado obtido (GET /queries/integration/{queryId})
201Consulta criada ou reprocessamento iniciado
400keys ausente ou vazio; falha na reserva do valor; limite de reprocessamentos atingido
401x-api-key ausente ou inválida
403Chave sem permissão para a rota
404Produto (slug) inexistente, consulta inexistente, organização não encontrada ou webhook não cadastrado
409Consulta duplicada, chaves que não atendem ao produto, organização inativa ou fora do canal integrador, reprocessamento não permitido
500Erro interno

Erros Mais Comuns​

Criar consulta (POST /queries/integration/{slug})​

HTTPerrormessageO que fazer
400MissingParamErrorkeysEnvie o objeto keys com ao menos uma chave preenchida
400ApplicationErrorFailed to reserve fundsSaldo/limite insuficiente, produto fora da sua tabela de preço ou cobrança inativa. A consulta fica como saldo_insuficiente e não é cobrada
404NotFoundErrorQuery template not found!Confira o slug do produto na API Reference
404NotFoundErrorWebhook not found!Cadastre o webhook no Portal do Integrador
409ConflictErrorYou must provide one of the combination of required keys!Envie ao menos uma das chaves aceitas pelo produto
409DuplicateQueryErrorA consulta referida de ... foi executada recentemente ...Use o data.existingQueryId ou reenvie com "duplicity": true para uma nova consulta (cobrada)
409ConflictErrorOrganization is not active!Fale com o suporte

Reprocessar (POST /queries/integration/{queryId}/reprocess)​

HTTPerrormessage
404NotFoundErrorQuery not found!
409ConflictErrorConsulta já foi processada com sucesso!
409ConflictErrorConsulta já está sendo reprocessada!
409ConflictErrorConsulta falhou, não pode ser reprocessada!
400MaxAttemptsExceededErrorMáximo de tentativas excedido!

Falha de Fonte não é Erro HTTP​

Quando uma fonte de dados fica indisponível, a API não responde com erro HTTP: a consulta termina com status parcial ou falha, e o campo servicesBroken lista as fontes que falharam. Veja Reprocessamento.

SituaçãoComo aparece no resultado
Fonte indisponívelStatus parcial (ou falha, se nada respondeu); fonte em servicesBroken; bloco ausente
Sem ocorrênciaBloco presente, com lista vazia ou indicador negativo (ex.: renajud: [], possuiIndicioSinistro: false)
Base sem dado para o veículoBloco ausente ou vazio, sem entrada em servicesBroken

Timeout ao Criar Consulta​

Se a resposta do POST não chegar, reenvie a mesma requisição sem duplicity. Se a primeira tiver sido criada, a API responde 409 DuplicateQueryError com o existingQueryId; use-o no GET. Assim você não paga duas vezes.

Próximos Passos​