Sign In

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

  1. HTTP 401 ou 403 exige corrigir autenticação ou acesso da conta.
  2. HTTP 413 ou 422 exige corrigir a solicitação; repetição sem correção mantém a rejeição.
  3. HTTP 402 exige saldo suficiente para a reserva.
  4. HTTP 409 com idempotency_conflict exige distinguir a solicitação original de uma nova operação; reutilizar a chave com outros dados não substitui o resultado existente.
  5. 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.
  6. HTTP 410 indica expiração e não deve ser tratado como indisponibilidade temporária.
  7. 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.