Códigos de Erro

Em caso de falha, verifique o código HTTP e o campo message.

Corpo de erro

Erros de negócio sempre retornam um code legível por máquina para ramificação programática. Parâmetros inválidos (validação) e rotas desconhecidas retornam o formato padrão do Laravel: { “message”: ”…”, “errors”: { … } }. Valide as entradas antes de enviar.

{
  "code": "insufficient_balance",
  "message": "Insufficient balance. Please top up and try again."
}

Erro

code	HTTP	Descrição
unauthorized	401	Chave de API ausente, inválida ou inativa.
account_banned	403	Conta suspensa. Fale com o suporte.
invalid_realtime_request	400	Requisição em tempo real malformada (ex.: número sem prefixo internacional + quando country é omitido).
idempotency_key_required	400	Requisições em tempo real exigem o cabeçalho Idempotency-Key.
invalid_idempotency_key	422	Idempotency-Key inválido: 1-128 caracteres de letras, dígitos e . _ : -
idempotency_conflict	409	A mesma Idempotency-Key foi usada com um conteúdo de requisição diferente.
request_in_progress	409	Uma requisição em tempo real idêntica ainda está sendo processada. Tente novamente em breve (Retry-After: 1).
empty_input	422	O arquivo enviado não contém linhas utilizáveis.
product_not_found	422	O slug de produto enviado não existe ou está inativo.
product_mode_not_supported	422	Este endpoint não aceita este modo de produto (produtos em tempo real não vão para endpoints em lote).
invalid_country	422	O produto não suporta o país enviado.
too_few_numbers	422	O envio está abaixo do mínimo do produto.
too_many_numbers	422	O envio excede o máximo da plataforma.
insufficient_balance	402	Saldo insuficiente. Recarregue e tente novamente.
realtime_disabled	403	A detecção em tempo real não está habilitada para esta conta.
realtime_rate_limited	429	Limite de requisições em tempo real excedido. Respeite o retry_after.
product_pricing_unavailable	503	O preço deste produto ainda não está configurado. Fale com o suporte.
detection_capacity_unavailable	503	Sem capacidade de detecção disponível no momento. Tente mais tarde.
realtime_route_unavailable	503	Nenhuma rota em tempo real disponível. Tente mais tarde.
realtime_fact_cache_unavailable	503	Uma dependência em tempo real está temporariamente indisponível. Tente mais tarde.
realtime_rate_limiter_unavailable	503	O limitador de requisições está temporariamente indisponível. Tente mais tarde.
internal_error	500	Erro interno do servidor. É seguro repetir com a mesma Idempotency-Key.

Falhas sem código

Nem toda falha tem um code. Os endpoints de tarefa informam quatro condições apenas com o status HTTP e message, porque essas falhas ocorrem antes de chegar ao caminho de erros de negócio:

HTTP	Condição	Corpo
404	O task_id não existe ou pertence a outra conta	apenas message
404	GET /v1/tasks/{token}/download — o arquivo de resultado está indisponível, expirou ou não está mais em estado baixável	apenas message
422	GET /v1/tasks/{token}/result — o resultado não está pronto: a tarefa não foi concluída, o arquivo não foi gerado ou expirou	apenas message
422	Os parâmetros da requisição falharam na validação	{ "message": …, "errors": { … } }

Nestes casos, ramifique pelo status HTTP. O message serve para os logs e para quem lê um incidente, não para o fluxo de controle.

Envie Accept: application/json

Esses corpos são JSON quando a requisição pede JSON. Um cliente que não envia o cabeçalho Accept pode receber uma página de erro HTML — algo penoso de depurar às 3 da manhã. Todos os exemplos desta documentação enviam JSON.

Tentar novamente

A resposta correta a uma falha depende de a repetição da requisição poder produzir um resultado diferente.

Ação necessária primeiro

Uma nova tentativa sem alterações repete a mesma falha.

unauthorized, account_banned, invalid_realtime_request, idempotency_key_required, invalid_idempotency_key, idempotency_conflict, empty_input, product_not_found, product_mode_not_supported, invalid_country, too_few_numbers, too_many_numbers, insufficient_balance, realtime_disabled, product_pricing_unavailable

Aguarde e tente novamente

Temporário — a mesma requisição deve funcionar mais tarde.

realtime_rate_limited, request_in_progress, detection_capacity_unavailable, realtime_route_unavailable, realtime_fact_cache_unavailable, realtime_rate_limiter_unavailable

Resultado incerto

A requisição pode ter sido aplicada ou não. Tente novamente com a mesma chave.

internal_error