Errores

Los fallos comparten un único sobre:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [{ "field": "payload.prompt", "message": "payload.prompt or payload.query is required" }],
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}

code es estable y seguro para ramificar. message es para personas y puede cambiar. details aparece cuando podemos identificar el campo problemático.

Códigos

Código	Estado	Significado	¿Reintentar?
`MISSING_API_KEY`	401	Token bearer ausente o incorrecto.	No: corrige la clave
`VALIDATION_ERROR`	400	Cuerpo mal formado, `taskType` desconocido o ausencia de `payload.prompt` y `payload.query`.	No: corrige la solicitud
`REGION_UNSUPPORTED`	422	Este motor nunca puede servir el `country` solicitado.	No: elige otro motor o región
`REGION_UNAVAILABLE`	422	Ahora mismo no hay capacidad para el `country` solicitado en este motor.	Más tarde, cuando vuelva la capacidad
`RESOURCE_ALREADY_EXISTS`	409	`idempotencyKey` duplicada en el endpoint individual.	No: la tarea ya existe
`PAYLOAD_TOO_LARGE`	413	El cuerpo del lote supera 8 MB.	No: envía bloques más pequeños
`RESOURCE_NOT_FOUND`	404	Id de tarea desconocido, o la tarea superó la ventana pública de sondeo de 24 horas.	No
`ENQUEUE_ERROR`	—	Fallo por elemento dentro de un lote (p. ej., un problema puntual de base de datos en un carril). Aparece en `results[].error`, nunca como estado HTTP.	Sí

400 es para una solicitud que no podemos parsear ni entender. 422 se reserva para una solicitud perfectamente formada que no podemos servir en la región pedida. Ramificar por error.code es más duradero que por el estado.

Rechazos por región

Ambos códigos de región se deciden antes de encolar la tarea, así lo sabes de inmediato en lugar de ver cómo una tarea agota sus reintentos y falla con un error que solo muestra el síntoma. REGION_UNSUPPORTED es permanente: ese motor no puede servir el país solicitado.

{
  "success": false,
  "error": {
    "code": "REGION_UNSUPPORTED",
    "message": "CHATGPT cannot be served for country='CN': no proxy vendor has exit supply in CN. This is a permanent capability gap, not a transient one — retrying will not help. GOOGLE and AIMODE are unaffected by exit-IP limits and remain available for this country.",
    "details": { "taskType": "CHATGPT", "country": "CN", "cause": "no_proxy_route", "retryable": false },
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}

Consulta la tabla de combinaciones no servibles. REGION_UNAVAILABLE es transitorio: la ruta existe pero ahora mismo nada puede servirla. Consulta GET /capacity para ver qué puede servir cada región en este momento.

Los fallos de lote son por elemento

Un lote bien formado siempre devuelve 200, aunque fallen todas sus tareas. El estado HTTP describe la solicitud; results[].success describe cada tarea.

{
  "success": true,
  "summary": { "total": 3, "succeeded": 2, "failed": 1 },
  "results": [
    { "success": true,  "index": 0, "task": { "...": "..." } },
    { "success": false, "index": 1, "error": { "code": "REGION_UNAVAILABLE", "message": "..." } },
    { "success": true,  "index": 2, "task": { "...": "..." } }
  ]
}

Solo una solicitud mal formada en su conjunto (no JSON, no es un array, vacía, más de 500 elementos, más de 8 MB o sin autorización) produce un 4xx para el lote en sí.

Un elemento del lote puede fallar con REGION_UNAVAILABLE o ENQUEUE_ERROR, y ninguno figura en el enum de errores por elemento del contrato de tareas asíncronas que implementa esta API. Son añadidos, no sustituciones: VALIDATION_ERROR y RESOURCE_ALREADY_EXISTS no cambian.

Fallos a nivel de tarea

Una tarea que falla después de entrar en cola no produce ningún error HTTP. Lo sabrás por el estado final:

{
  "success": true,
  "task": { "id": "8f2c1e40-...", "status": "FAILED", "...": "..." },
  "credits": { "creditsToCharge": 0, "creditsCharged": 0 },
  "error": "ENGINE_TIMEOUT: The engine did not answer before the task deadline."
}

Fíjate en la diferencia de forma: este error de nivel superior es una cadena, no el objeto {code, message, timestamp} de los errores de solicitud. Empieza con un código seguido de una frase fija para ese código, así que decide según el código: ENGINE_TIMEOUT, ENGINE_NO_RESULT, ENGINE_FAILED, o NO_IP_AVAILABLE y NO_ACCOUNT_AVAILABLE cuando no se liberó capacidad a tiempo (reintentar más tarde suele funcionar). BAD_PAYLOAD y PAGE_UNAVAILABLE (una página de Naver que no se puede leer de forma anónima) conservan un mensaje que indica qué cambiar. La misma tarea entrega un webhook con task.status === "FAILED".

Primeros pasos

Conceptos clave

Motores

Source Influence

Prompt Research

Monitorización GEO

Migración

Códigos

Rechazos por región

Los fallos de lote son por elemento

Fallos a nivel de tarea

​Códigos

​Rechazos por región

​Los fallos de lote son por elemento

​Fallos a nivel de tarea

Códigos

Rechazos por región

Los fallos de lote son por elemento

Fallos a nivel de tarea