Como a Routal reporta erros de API?

Toda resposta não-2xx devolve o mesmo envelope JSON: { "message": "...", "message_id": "highway. .error. " }. Bifurque por message_id — o texto pode mudar entre releases; o ID é estável.

Quais códigos HTTP devo retry?

Retry apenas 429 (rate limit) e 5xx, com backoff exponencial e jitter. Outros 4xx falharão da mesma forma — corrija a requisição antes de reenviar.

Como distingo falha de autenticação de recurso inexistente?

401 significa private_key ausente ou inválida (message_id highway.apiKey.error.not_found). 404 significa que o ID não existe ou não é visível para a sua chave. 403 significa autenticado mas sem permissão no recurso.

Errors · Routal API

Todo erro da API da Routal devolve um envelope JSON com dois campos: message (legível para humanos, pode mudar) e message_id (estável, machine-readable). Sempre bifurque seu tratamento de erros por message_id, nunca pelo texto de message.

{
  "message": "API key not found",
  "message_id": "highway.apiKey.error.not_found",
  "statusCode": 401
}

O catálogo completo de message_id por domínio (apiKey, plan, route, stop, task, vehicle, optimization, geocoding, validation) e a árvore de decisão por código vive na versão inglesa desta página.

A referência técnica completa de error codes, com tabela por domínio e padrões de retry recomendados, vive em inglês.

Ler a referência completa em inglês →