Saltar al contenido principal
Una solicitud que la API rechaza devuelve un estado HTTP de error y este sobre:
code es estable; ramifica por él. message es para personas y puede cambiar. details aparece cuando hay algo que añadir: normalmente un array de { field, message } en un error de validación, o un objeto como { "id": "..." } o { "retryAfterSec": 5, "retryable": true }. Una tarea que se acepta y después falla no produce un error HTTP. En su lugar informa un código de fallo de tarea.

Códigos de error de solicitud

Prefiere error.code al estado: VALIDATION_ERROR aparece tanto como 400 como 422. Un 429 indica que alcanzaste uno de tus propios límites; un 503, que nos falta capacidad por el momento.

Retry-After

En POST /v1/async/task, POST /v1/async/task/batch y POST /v1/async/task/grid, todo 429 y 503 lleva un encabezado Retry-After en segundos. La mayoría de estos códigos también llevan details.retryAfterSec y details.retryable: true. Los 429 del límite de solicitudes del edge no llevan ninguno de los dos. Consulta Créditos y límites.

Límites de tamaño del payload

Rechazos por región

REGION_UNSUPPORTED se decide antes de encolar la tarea, así lo sabes de inmediato en lugar de esperar a que la tarea falle:
Qué motores sirven qué países está en Regiones y ubicación.

Errores por elemento en lotes y cuadrículas

En POST /v1/async/task/batch, una solicitud bien formada devuelve 200 aunque fallen elementos. El estado describe la solicitud; results[].success describe cada tarea, y un elemento fallido lleva el mismo objeto { code, message, details, timestamp } que un error de solicitud:
Un elemento que falló con un código 429, QUEUE_BACKPRESSURE o SERVER_OVERLOADED lleva su espera en details.retryAfterSec. La solicitud en sí solo falla con 400, 413, 429 o 503 cuando se rechaza el lote entero. POST /v1/async/task/grid informa de los puntos rechazados de la misma forma en points[]. POST /v1/batches rechaza el lote entero con 400 si algún elemento no es válido, y guarda como REJECTED los elementos que la admisión rechaza, por ejemplo por INSUFFICIENT_CREDITS. Un elemento cuya idempotencyKey coincidió con una tarea creada antes del lote aparece como FAILED con TASK_NOT_RETAINED cuando esa tarea deja de conservarse. Consulta Lotes y cuadrículas.

Códigos de fallo de tareas

Una tarea que falla después de entrar en cola termina en FAILED. El sondeo devuelve una cadena error de nivel superior, no el objeto de error de solicitud:
El webhook lleva la misma cadena en response.error. La cadena empieza por un código; ramifica por él.

Cambios en los códigos de fallo de tarea