Erros da API
Last updated
Rejeições de requisição e falhas de execução usam o HTTP correspondente e um objeto error. As mensagens são explicativas; integrações devem tomar decisões a partir do HTTP e de error.code.
{
"error": {
"code": "invalid_input",
"message": "Confira os dados informados.",
"request_id": "639454ac-4dcc-4a56-a240-bc273424f40a"
}
}
O identificador é sintético. error.request_id identifica a requisição HTTP e corresponde ao rastreamento em X-Request-Id. Ele não é o identificador de uma operação para GET /queries ou GET /batches.
Formato
| Campo | Tipo | Descrição |
|---|---|---|
error.code |
String | Código legível por máquina. |
error.message |
String | Mensagem em português. |
error.request_id |
String UUID | Identificador de rastreamento HTTP. |
error.details |
Objeto, opcional | Detalhes públicos adicionais. Usado para saldo insuficiente. |
As respostas de erro usam Cache-Control: no-store. Não incluem credenciais, o documento enviado ou dados de resultado.
Autenticação e acesso
| Código | HTTP | Significado |
|---|---|---|
invalid_api_key |
401 | Cabeçalho Bearer ausente ou inválido, chave inválida ou revogada. |
account_not_verified |
403 | A conta precisa confirmar o e-mail. |
account_suspended |
403 | A conta está suspensa. |
api_access_disabled |
403 | O acesso às consultas está desabilitado. |
terms_acceptance_required |
403 | A conta precisa aceitar os termos atuais. |
Trocar a chave não elimina uma restrição da conta. Operações existentes também exigem acesso válido para recuperação. O formato de autenticação está em autenticação.
Entrada e idempotência
| Código | HTTP | Significado |
|---|---|---|
invalid_content_type |
422 | POST de consulta ou lote não enviado em application/json. |
malformed_json |
422 | Corpo JSON inválido. |
invalid_input |
422 | Corpo, documento, placa, chave de idempotência, parâmetros ou cursor inválidos. |
invalid_input |
413 | Corpo acima do limite de 32 KiB. |
idempotency_conflict |
409 | A chave de idempotência já identifica outra solicitação. |
batch_not_supported |
422 | O dataset não aceita consultas em lote. |
invalid_metrics_period |
422 | Período de métricas não reconhecido. |
invalid_metrics_range |
422 | Intervalo customizado inválido, sem fuso explícito, invertido ou maior que 366 dias. |
As regras de corpo e idempotência estão em requisições e cobrança; cursores e validação por item estão em lotes. Erros individuais de entrada em um lote válido são registrados em data.failed, e não tornam necessariamente o POST inteiro um HTTP 422.
Saldo
| Código | HTTP | Significado |
|---|---|---|
insufficient_balance |
402 | O saldo disponível não cobre a reserva necessária para a operação. |
Esse erro inclui detalhes em centavos de real:
{
"error": {
"code": "insufficient_balance",
"message": "Saldo insuficiente para esta consulta.",
"request_id": "639454ac-4dcc-4a56-a240-bc273424f40a",
"details": {
"required_cents": 248,
"available_cents": 100,
"currency": "BRL"
}
}
}
Campo de details |
Tipo | Significado |
|---|---|---|
required_cents |
Inteiro não negativo | Reserva exigida. Em lote, considera somente itens válidos e únicos. |
available_cents |
Inteiro | Saldo disponível no momento da verificação. |
currency |
String | Sempre BRL. |
Valores e identificador do exemplo são ilustrativos. A rejeição por saldo insuficiente ocorre antes da execução da consulta.
Identificadores e retenção
| Código | HTTP | Significado |
|---|---|---|
dataset_not_found |
404 | Dataset não reconhecido. |
query_not_found |
404 | Consulta inexistente, identificador inválido ou operação não associada à chave usada. |
batch_not_found |
404 | Lote inexistente, identificador inválido ou operação não associada à chave usada. |
route_not_found |
404 | Caminho ou método não reconhecido pela API. |
query_expired |
410 | Resultado de consulta fora do prazo de recuperação. |
batch_expired |
410 | Resultados de lote fora do prazo de recuperação. |
Por padrão, consulta individual expira 48 horas após a criação, e lote e consultas pertencentes a ele expiram 48 horas após o fechamento. Se a conta desabilitar a retenção de 48 horas em Configurações, novas operações expiram 5 minutos após a conclusão da consulta ou do lote. A preferência não altera operações existentes. O limite definitivo está em expires_at. HTTP 410 é terminal para a recuperação: novas leituras ou replays não renovam o prazo nem reiniciam a operação.
Disponibilidade e execução
| Código | HTTP | Significado |
|---|---|---|
dataset_unavailable |
503 | Dataset temporariamente indisponível para execução. |
dataset_pricing_invalid |
503 | Preço indisponível para executar a consulta. |
provider_unavailable |
503, 502, 409 ou 404 | Não foi possível concluir a consulta. O HTTP mais comum é 503; outras falhas de conclusão podem usar 502, 409 ou 404. |
provider_invalid_response |
502 | O resultado obtido não pôde ser processado no contrato da consulta. |
provider_timeout |
504 | A consulta não foi concluída dentro do prazo. |
result_unavailable |
503 | Resultado existente temporariamente indisponível para recuperação. |
service_unavailable |
503 | Serviço temporariamente indisponível. |
O nome de um código não altera a regra de cobrança: consulta no_data ou failed não é cobrada. Uma falha de recuperação de uma consulta já succeeded ou partial não cria outra consulta nem gera outra cobrança.
Uma resposta 5xx ou perda de conexão não comprova que a operação deixou de ser criada. A recuperação segura usa o identificador conhecido ou repete o POST com a mesma chave de idempotência e a mesma solicitação.
Limites de lotes
| Código | HTTP | Significado |
|---|---|---|
batch_limit_exceeded |
429 | Limite de lotes simultâneos da conta atingido. |
batch_rate_limited |
429 | Limite de novas solicitações de lote por minuto atingido. |
webhook_limit_exceeded |
429 | Limite de entregas webhook pendentes da conta atingido. |
batch_capacity_exceeded |
503 | Capacidade de processamento ou entrega temporariamente ocupada. |
batch_executor_unavailable |
503 | Processamento de lotes temporariamente indisponível. |
Esses cinco códigos incluem Retry-After: 60, em segundos. O cabeçalho orienta o intervalo de espera; não garante disponibilidade ao final dele. Lotes já aceitos podem ser acompanhados com GET /batches/{request_id}.
Em respostas normais de lote ainda processing, o cabeçalho é Retry-After: 2, junto de HTTP 202. Isso é acompanhamento da operação, não um erro de limite.
Falhas de itens em lote
O objeto data.failed de lote concluído e os eventos de item usam códigos diferentes dos erros HTTP. Cada entrada contém index, key, code e message.
| Código do item | Significado |
|---|---|
invalid_input |
Entrada inválida; não aceita para execução e sem reserva. |
duplicate_input |
Entrada repetida após normalização; não aceita para execução e sem reserva. |
query_failed |
Falha ao concluir a consulta aceita. |
query_timeout |
Consulta não concluída dentro do prazo. |
access_disabled |
Acesso desabilitado antes da execução do item. |
Todos esses itens são considerados falhos e não são cobrados. Um lote pode ter HTTP 200 e status: "completed" com itens falhos, inclusive sem nenhum sucesso. O estado no_data permanece na lista própria e não recebe código de falha.
Estratégia de recuperação
- HTTP 401 ou 403 exige corrigir autenticação ou acesso da conta.
- HTTP 413 ou 422 exige corrigir a solicitação; repetição sem correção mantém a rejeição.
- HTTP 402 exige saldo suficiente para a reserva.
- HTTP 409 com
idempotency_conflictexige distinguir a solicitação original de uma nova operação; reutilizar a chave com outros dados não substitui o resultado existente. - HTTP 404 com código de operação não encontrada exige conferir endpoint, identificador, conta e chave de API usada originalmente. Com
provider_unavailable, ele representa falha de conclusão e não comprova que nenhuma operação foi criada. - HTTP 410 indica expiração e não deve ser tratado como indisponibilidade temporária.
- Limites e indisponibilidade temporária permitem nova recuperação com espera. O mesmo identificador ou a mesma chave idempotente evita criar uma operação adicional por incerteza.
Uma operação recuperada como failed é terminal e vem em envelope normal, com HTTP 200. Consultar novamente não reexecuta o trabalho. A decisão de realizar nova consulta deve usar uma nova chave de idempotência e considerar que ela será uma nova operação, sujeita ao preço e à disponibilidade vigentes.