Errores

Ramifica según el código de error, nunca según el mensaje. La tabla se genera a partir del documento OpenAPI.

Errores

Estado	Código	Significado
400	invalid_request	Error de esquema. details.path apunta al campo problemático.
401	unauthorized	Clave de API ausente o desconocida.
402	quota_exceededRetry-After	Cuota mensual alcanzada. Retry-After da los segundos que faltan hasta que cambia el mes.
403	key_revoked	La clave existe pero no puede usarse: ha sido revocada, o la suscripción a la Engine API de la cuenta ya no está activa. El campo message indica cuál de las dos.
404	not_found	No existe esa ruta — también es lo que obtienes por la ruta correcta con el método equivocado.
409	idempotency_conflictRetry-After	Solo con la cabecera Idempotency-Key: la clave ya se usó para otra solicitud (idempotency_conflict — use una clave nueva), o la primera solicitud con ella sigue en curso (idempotency_in_progress — reintente tras Retry-After para recibir su respuesta). Nunca se cobra.
409	idempotency_in_progressRetry-After	Solo con la cabecera Idempotency-Key: la clave ya se usó para otra solicitud (idempotency_conflict — use una clave nueva), o la primera solicitud con ella sigue en curso (idempotency_in_progress — reintente tras Retry-After para recibir su respuesta). Nunca se cobra.
413	too_large	Entrada por encima de un límite (ver Límites).
429	busyRetry-After	Momentáneamente al máximo de capacidad o — en cualquier ruta autenticada con clave — tu dirección envió demasiadas claves API desconocidas en un minuto. Retry-After en segundos; esto nunca cuenta contra tu cuota.
500	internal	Error inesperado, o el backend de autenticación es inaccesible (las solicitudes fallan en cerrado).
503	service_unavailable	Un motor solicitado no puede servirse ahora mismo — el motor de nesting o el motor max asíncrono. Para max hay dos causas, y el campo message indica cuál: el nivel no está incluido en este despliegue, o sí lo está pero el worker que resuelve los trabajos no responde. Fail-closed antes de reservar una llamada, así que nunca cuesta nada.
504	solve_timeout	El cálculo superó su límite estricto de tiempo. En las rutas rectangulares lo impone el proxy; en /v1/optimize/nest el motor impone su propio presupuesto, más corto, y responde con solve_timeout en el envoltorio habitual. Una llamada que el proxy abandonó no se cobra.

Cuerpo del error

Cada error que produce el propio motor usa el mismo envoltorio. Ramifica sobre error, que es un código estable; nunca sobre message, cuya redacción puede cambiar entre versiones. details está presente en invalid_request, donde path nombra el campo problemático, y en too_large, donde max y got dan el límite y lo que enviaste.

La excepción es un cuerpo de petición por encima del límite de tamaño: lleva maxBytes en su lugar. Un engine desconocido añade available, los ids de engine que acepta este despliegue.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "invalid_request",
  "message": "parts[0].h: must be greater than 0",
  "details": { "path": "parts[0].h" }
}

HTTP/1.1 402 Payment Required
Retry-After: 41400
Content-Type: application/json; charset=utf-8

{ "error": "quota_exceeded", "message": "monthly quota exhausted" }

402 y 429 llevan ambos una cabecera Retry-After en segundos. En 402 cuenta hacia atrás hasta el reinicio de la cuota a las 00:00 UTC del día 1 del mes siguiente; en 429 es una breve espera, y un 429 nunca consume cuota — la llamada reservada se devuelve.
Los rechazos de la clave de demostración pública usan el mismo sobre: fuera de su alcance (nesting, el motor max, usage, jobs, import, un trabajo por encima de sus límites de tamaño) un 403 key_revoked con details.reason "demo_scope"; en su límite de frecuencia un 429 busy con details.reason "demo_rate_limit" y details.limit.
Ambos llevan details.testKeyUrl, donde se crea una clave de prueba gratuita, y cada respuesta de demostración trae la cabecera X-CutOptim-Demo: true.
Un fallo de enrutamiento responde con not_found, un código deliberadamente fuera de la lista anterior porque lo produce el enrutador y no el contrato de la API. Obtienes 404 y no 405 cuando la ruta es correcta pero el método es equivocado: los cuatro endpoints de optimización aceptan solo POST.
En las rutas rectangulares el 504 procede del proxy inverso, no del motor, así que su cuerpo es el del proxy y no este envoltorio JSON; un solo trabajo dentro de los límites de entrada de abajo queda muy por debajo, pero varios de los trabajos más pesados a la vez pueden superarlo en la cola — y una llamada que el proxy abandonó no se cobra. /v1/optimize/nest es la excepción: ese cálculo es un subproceso con su propio presupuesto, mantenido deliberadamente por debajo del límite del proxy, así que allí un tiempo agotado sí usa este envoltorio, con el código solve_timeout.

¿Se ha caído un motor? La página de estado muestra en vivo el estado del sitio web, la Engine API, el motor de nesting y el motor asíncrono max: Estado del servicio ↗