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"
}
}
| Campo | Descrição |
|---|---|
statusCode | Código HTTP |
timestamp | Momento do erro (ISO-8601 UTC) |
path | Rota chamada |
error | Tipo do erro (ex.: NotFoundError, ConflictError) |
message | Descrição do erro |
data | Presente só em DuplicateQueryError, com a consulta já existente |
Códigos de Status HTTP
| Código | Quando acontece |
|---|---|
| 200 | Resultado obtido (GET /queries/integration/{queryId}) |
| 201 | Consulta criada ou reprocessamento iniciado |
| 400 | keys ausente ou vazio; falha na reserva do valor; limite de reprocessamentos atingido |
| 401 | x-api-key ausente ou inválida |
| 403 | Chave sem permissão para a rota |
| 404 | Produto (slug) inexistente, consulta inexistente, organização não encontrada ou webhook não cadastrado |
| 409 | Consulta duplicada, chaves que não atendem ao produto, organização inativa ou fora do canal integrador, reprocessamento não permitido |
| 500 | Erro interno |
Erros Mais Comuns
Criar consulta (POST /queries/integration/{slug})
| HTTP | error | message | O que fazer |
|---|---|---|---|
| 400 | MissingParamError | keys | Envie o objeto keys com ao menos uma chave preenchida |
| 400 | ApplicationError | Failed to reserve funds | Saldo/limite insuficiente, produto fora da sua tabela de preço ou cobrança inativa. A consulta fica como saldo_insuficiente e não é cobrada |
| 404 | NotFoundError | Query template not found! | Confira o slug do produto na API Reference |
| 404 | NotFoundError | Webhook not found! | Cadastre o webhook no Portal do Integrador |
| 409 | ConflictError | You must provide one of the combination of required keys! | Envie ao menos uma das chaves aceitas pelo produto |
| 409 | DuplicateQueryError | A consulta referida de ... foi executada recentemente ... | Use o data.existingQueryId ou reenvie com "duplicity": true para uma nova consulta (cobrada) |
| 409 | ConflictError | Organization is not active! | Fale com o suporte |
Reprocessar (POST /queries/integration/{queryId}/reprocess)
| HTTP | error | message |
|---|---|---|
| 404 | NotFoundError | Query not found! |
| 409 | ConflictError | Consulta já foi processada com sucesso! |
| 409 | ConflictError | Consulta já está sendo reprocessada! |
| 409 | ConflictError | Consulta falhou, não pode ser reprocessada! |
| 400 | MaxAttemptsExceededError | Má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ção | Como aparece no resultado |
|---|---|
| Fonte indisponível | Status parcial (ou falha, se nada respondeu); fonte em servicesBroken; bloco ausente |
| Sem ocorrência | Bloco presente, com lista vazia ou indicador negativo (ex.: renajud: [], possuiIndicioSinistro: false) |
| Base sem dado para o veículo | Bloco 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.