# Errori

Ogni errore è in formato JSON con un campo `error` leggibile dall'utente e un campo `code` stabile. Creare un ramo in base al campo `code`, non al messaggio.

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

## Genera errori

| HTTP | codice | Cosa è successo | Riprovare? |
|---|---|---|---|
| 400 | `BAD_INPUT` | Non è stato possibile leggere il corpo | No, correggi la richiesta |
| 400 | `NO_PERSON` | L'immagine della persona manca, è illeggibile o non è in un formato supportato | No, invia un'immagine valida |
| 400 | `NO_GARMENT` | L'immagine del capo è mancante, illeggibile o l'`garment_url` è bloccato | No, invia un'immagine valida o un URL https pubblico |
| 401 | `NO_KEY` | Assenza dell'intestazione `X-API-KEY` | No |
| 401 | `INVALID_KEY` | Codice errato o revocato | No, controlla la chiave nel cruscotto |
| 402 | `NO_CREDITS` | Crediti acquistati esauriti | No, [acquista crediti](/pricing#developer-api) |
| 402 | `QUOTA_EXCEEDED` | La quota gratuita è esaurita | No, acquista crediti |
| 402 | `KEY_LIMIT_REACHED` | Questa chiave API ha raggiunto il limite di credito mensile. Il corpo del messaggio include i campi `used` e `limit` | No, aspetta il 1° (UTC) oppure usa una chiave con un limite più alto |
| 402 | `FREE_TRIAL_USED` | La versione di prova gratuita è già stata utilizzata su questo dispositivo | No, acquista crediti |
| 403 | `DEVICE_BANNED` | Questo dispositivo è stato bloccato a causa di un uso improprio | No, contatta l'assistenza |
| 400 | `BAD_IDEMPOTENCY_KEY` | `Idempotency-Key` è vuoto, troppo lungo o contiene spazi | No, correggi l'intestazione |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | Una richiesta con questa chiave è ancora in esecuzione. Nessun addebito | Sì, dopo `Retry-After` |
| 409 | `IDEMPOTENCY_REPLAY` | Questa chiave ha già funzionato. Non è stato addebitato alcun importo. | No, la prima risposta conteneva l'immagine |
| 409 | `IDEMPOTENCY_MISMATCH` | Questa chiave è stata utilizzata con immagini diverse | No, usa una nuova chiave |
| 413 | `IMAGE_TOO_LARGE` | Un'immagine supera i 15 MB | No, prima riduci la scala |
| 422 | `CONTENT_FILTERED` | Bloccato a causa della moderazione dei contenuti. Credito rimborsato | No, usa immagini diverse |
| 429 | `RATE_LIMITED` | Troppe richieste | Sì, dopo `Retry-After` secondi |
| 500 | `GENERATION_FAILED` | Il motore si è guastato. Importo rimborsato | Sì, una volta |

## Operazioni asincrone e elaborazioni in batch

| HTTP | codice | Cosa è successo | Riprovare? |
|---|---|---|---|
| 400 | `BAD_WEBHOOK_URL` | `webhook_url` non è un URL `https` pubblico | No, correggi l'URL |
| 400 | `BATCH_TOO_LARGE` | Oltre 500 articoli, ovvero più di 10 in modalità di prova | No, dividi il lotto |
| 402 | `ASYNC_NEEDS_CREDITS` | I lavori asincroni e i batch utilizzano i crediti acquistati | No, acquista crediti oppure usa `POST /generate` |
| 429 | `TOO_MANY_JOBS` | 50 processi asincroni già in esecuzione sull'account | Sì, dopo `Retry-After` |
| 500 | `JOB_CREATE_FAILED`, `BATCH_CREATE_FAILED` | Impossibile crearlo. Crediti rimborsati | Sì |

Un’attività che fallisce dopo essere stata accettata riporta il codice `error.code` sia nell’attività stessa che nel webhook `generation.failed`: `CONTENT_FILTERED`, `GENERATION_FAILED` o `INPUT_FETCH_FAILED` (impossibile scaricare l’URL di un’immagine). Il credito corrispondente viene rimborsato. Le voci del batch annullate mostrano lo stato `CANCELLED`.

## Altri endpoint

| Endpoint | HTTP | codice | Riprovare? |
|---|---|---|---|
| `GET /credits` | 500 | `CREDITS_UNAVAILABLE` | Sì |
| `GET /results/:id` | 404 | `NOT_FOUND` (sconosciuto, non tuo o risalente a più di 7 giorni fa) | No |
| `DELETE /customers/:id` | 500 | `DELETE_FAILED` (non è stato cancellato nulla) | Sì |
| `DELETE /results/:id` | 404 | `NOT_FOUND` | No |
| `DELETE /results/:id` | 500 | `DELETE_FAILED` | Sì |

## Istruzioni per l'uso consigliate

```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")
}
```

> **Avviso:** non riprovare mai con un codice `402` in un ciclo. Significa che l'account ha esaurito i crediti.
