# Errores

Cada error está en formato JSON y contiene un campo `error` legible para el usuario y un `code` estable. Toma decisiones en función del `code`, no del mensaje.

```json
{ "error": "No credits left. Top up your developer wallet to continue.", "code": "NO_CREDITS" }
```

## Generar errores

| HTTP | código | ¿Qué pasó? | ¿Lo intentas de nuevo? |
|---|---|---|---|
| 400 | `BAD_INPUT` | No se ha podido leer el cuerpo del mensaje | No, corrige la solicitud. |
| 400 | `NO_PERSON` | Falta la imagen de la persona, es ilegible o no tiene un formato compatible | No, envía una imagen válida |
| 400 | `NO_GARMENT` | Falta la imagen de la prenda, es ilegible o la URL `garment_url` está bloqueada | No, envía una imagen válida o una URL pública https |
| 401 | `NO_KEY` | No hay encabezado `X-API-KEY` | No |
| 401 | `INVALID_KEY` | Clave incorrecta o revocada | No, comprueba la llave en el salpicadero. |
| 402 | `NO_CREDITS` | Créditos comprados agotados | No, [comprar créditos](/pricing#developer-api) |
| 402 | `QUOTA_EXCEEDED` | Se ha agotado la asignación gratuita | No, comprar créditos |
| 402 | `KEY_LIMIT_REACHED` | Esta clave de API ha alcanzado su límite de crédito mensual. El cuerpo del mensaje incluye `used` y `limit` | No, espera hasta el día 1 (UTC) o utiliza una clave con un límite más alto |
| 402 | `FREE_TRIAL_USED` | La prueba gratuita ya se ha utilizado en este dispositivo. | No, comprar créditos |
| 403 | `DEVICE_BANNED` | Este dispositivo ha sido bloqueado por uso indebido | No, ponte en contacto con el servicio de asistencia |
| 400 | `BAD_IDEMPOTENCY_KEY` | `Idempotency-Key` está vacío, es demasiado largo o contiene espacios | No, corrige el encabezado. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | Todavía hay una solicitud con esta clave en curso. No se ha cobrado nada. | Sí, después de `Retry-After` |
| 409 | `IDEMPOTENCY_REPLAY` | Esta clave ya ha funcionado. No se ha cobrado nada. | No, la primera respuesta incluía la imagen |
| 409 | `IDEMPOTENCY_MISMATCH` | Esta clave se utilizó con diferentes imágenes | No, utiliza una clave nueva. |
| 413 | `IMAGE_TOO_LARGE` | Una imagen ocupa más de 15 MB | No, primero hay que reducir la escala |
| 422 | `CONTENT_FILTERED` | Bloqueado por motivos de moderación de contenidos. Se ha reembolsado el importe. | No, utiliza imágenes diferentes |
| 429 | `RATE_LIMITED` | Demasiadas solicitudes | Sí, tras `Retry-After` segundos |
| 500 | `GENERATION_FAILED` | El motor ha fallado. Se ha devuelto el importe. | Sí, una vez |

## Tareas asíncronas y lotes

| HTTP | código | ¿Qué pasó? | ¿Lo intentas de nuevo? |
|---|---|---|---|
| 400 | `BAD_WEBHOOK_URL` | `webhook_url` no es una URL pública `https` | No, corrige la URL |
| 400 | `BATCH_TOO_LARGE` | Más de 500 artículos, o más de 10 en modo de prueba | No, divide el lote |
| 402 | `ASYNC_NEEDS_CREDITS` | Las tareas asíncronas y los lotes consumen los créditos adquiridos | No, compra créditos o utiliza `POST /generate` |
| 429 | `TOO_MANY_JOBS` | Ya hay 50 tareas asíncronas en ejecución en la cuenta | Sí, después de `Retry-After` |
| 500 | `JOB_CREATE_FAILED`, `BATCH_CREATE_FAILED` | No se ha podido crear. Se han devuelto los créditos. | Sí |

Un trabajo que falla tras haber sido aceptado muestra el código de e`error.code`, tanto en el propio trabajo como en el webhook `generation.failed`: `CONTENT_FILTERED`, `GENERATION_FAILED` o `INPUT_FETCH_FAILED` (no se ha podido descargar la URL de una imagen). Se reembolsa el crédito correspondiente. Los elementos del lote cancelados muestran el estado `CANCELLED`.

## Otros criterios de valoración

| Punto final | HTTP | código | ¿Lo intentas de nuevo? |
|---|---|---|---|
| `GET /credits` | 500 | `CREDITS_UNAVAILABLE` | Sí |
| `GET /results/:id` | 404 | `NOT_FOUND` (desconocido, no es tuyo o tiene más de 7 días) | No |
| `DELETE /customers/:id` | 500 | `DELETE_FAILED` (no se ha borrado nada) | Sí |
| `DELETE /results/:id` | 404 | `NOT_FOUND` | No |
| `DELETE /results/:id` | 500 | `DELETE_FAILED` | Sí |

## Manipulación recomendada

```js
async function tryOn(form) {
  for (let attempt = 1; attempt <= 2; attempt++) {
    const res = await fetch("https://www.tryoncloud.com/api/v1/generate", {
      method: "POST",
      headers: { "X-API-KEY": process.env.TRYONCLOUD_API_KEY },
      body: form,
      signal: AbortSignal.timeout(120_000),
    })
    if (res.ok) return Buffer.from(await res.arrayBuffer())

    const { code, error } = await res.json()
    if (code === "RATE_LIMITED") {
      await new Promise((r) => setTimeout(r, Number(res.headers.get("Retry-After") || 5) * 1000))
      continue
    }
    if (code === "GENERATION_FAILED" && attempt === 1) continue // refunded, retry once
    throw new Error(`${code}: ${error}`) // 4xx: fix input or buy credits, do not loop
  }
  throw new Error("GENERATION_FAILED twice")
}
```

> **Advertencia:** Nunca vuelvas a intentar un `402` en un bucle. Significa que la cuenta se ha quedado sin créditos.
