¿Cómo reporta Routal los errores de API?

Cada respuesta no-2xx devuelve el mismo envelope JSON: { "message": "...", "message_id": "highway. .error. " }. Bifurca por message_id — el texto puede cambiar entre releases; el ID es estable.

¿Qué códigos HTTP debo reintentar?

Reintenta solo 429 (rate limit) y 5xx, con backoff exponencial y jitter. El resto de 4xx fallarán igual al reintentar — corrige la request antes de reenviarla.

¿Cómo distingo un fallo de autenticación de un recurso inexistente?

401 significa private_key ausente o inválida (message_id highway.apiKey.error.not_found). 404 significa que el ID no existe o no es visible para tu key. 403 significa autenticado pero sin permisos sobre ese recurso.

Errors · Routal API

Cada error de la API de Routal devuelve un envelope JSON con dos campos: message (legible por humanos, puede cambiar) y message_id (estable, machine-readable). Bifurca tu manejo de errores siempre por message_id, nunca por el texto de message.

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

El catálogo completo de message_id por dominio (apiKey, plan, route, stop, task, vehicle, optimization, geocoding, validation) y el árbol de decisión por código vive en la versión inglesa de esta página.

La referencia técnica completa de error codes, con tabla por dominio y patrones de retry recomendados, vive en inglés.

Leer la referencia completa en inglés →