> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errores

> El sobre de error, todos los códigos que devuelve la API y qué merece un reintento.

Los fallos comparten un único sobre:

```json theme={null}
{
  "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í |

<Note>
  `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.
</Note>

## 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.

```json theme={null}
{
  "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](/es/engines/capacity).

`REGION_UNAVAILABLE` es transitorio: la ruta existe pero ahora mismo nada puede servirla. Consulta
[`GET /capacity`](/es/api-reference/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*.

```json theme={null}
{
  "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í.

<Note>
  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.
</Note>

## 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:

```json theme={null}
{
  "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"`.