# Erreurs

Chaque erreur est au format JSON et comporte un champ `error` lisible par l'utilisateur ainsi qu'un champ `code` stable. Baser la prise de décision sur le `code`, et non sur le message.

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

## Générer des erreurs

| HTTP | code | Que s'est-il passé ? | Réessayer ? |
|---|---|---|---|
| 400 | `BAD_INPUT` | Le corps n'a pas pu être identifié | Non, corrigez la requête. |
| 400 | `NO_PERSON` | L'image de la personne est manquante, illisible ou n'est pas au format pris en charge | Non, envoyez une image valide |
| 400 | `NO_GARMENT` | Image du vêtement manquante, illisible ou URL `garment_url` bloquée | Non, envoyez une image valide ou une URL https publique |
| 401 | `NO_KEY` | Absence d'en-tête `X-API-KEY` | Non |
| 401 | `INVALID_KEY` | Clé incorrecte ou révoquée | Non, vérifie la clé dans le tableau de bord. |
| 402 | `NO_CREDITS` | Crédits achetés épuisés | Non, [acheter des crédits](/pricing#developer-api) |
| 402 | `QUOTA_EXCEEDED` | Le quota gratuit est épuisé | Non, acheter des crédits |
| 402 | `KEY_LIMIT_REACHED` | Cette clé API a atteint sa limite de crédit mensuelle. Le corps du message contient les champs `used` et `limit` | Non, attendez le 1er (UTC) ou utilisez une clé avec une limite plus élevée |
| 402 | `FREE_TRIAL_USED` | La période d'essai gratuite a déjà été utilisée sur cet appareil. | Non, acheter des crédits |
| 403 | `DEVICE_BANNED` | Cet appareil a été bloqué pour cause d'utilisation abusive | Non, contactez le service d'assistance |
| 400 | `BAD_IDEMPOTENCY_KEY` | La `Idempotency-Key` est vide, trop longue ou contient des espaces | Non, corrige l'en-tête. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | Une requête associée à cette clé est toujours en cours d'exécution. Aucun montant n'a été débité. | Oui, après `Retry-After` |
| 409 | `IDEMPOTENCY_REPLAY` | Cette clé a déjà fonctionné. Rien n'a été facturé. | Non, c'est la première réponse qui contenait l'image |
| 409 | `IDEMPOTENCY_MISMATCH` | Cette clé a été utilisée avec différentes images | Non, utilisez une nouvelle clé |
| 413 | `IMAGE_TOO_LARGE` | Une image fait plus de 15 Mo | Non, commence par réduire l'échelle |
| 422 | `CONTENT_FILTERED` | Bloqué par le contrôle des contenus. Crédit remboursé | Non, utilise d'autres images |
| 429 | `RATE_LIMITED` | Trop de demandes | Oui, après `Retry-After` secondes |
| 500 | `GENERATION_FAILED` | Le moteur est tombé en panne. Le crédit a été remboursé. | Oui, une fois |

## Tâches asynchrones et traitements par lots

| HTTP | code | Que s'est-il passé ? | Réessayer ? |
|---|---|---|---|
| 400 | `BAD_WEBHOOK_URL` | `webhook_url` n'est pas une URL `https` publique | Non, corrige l'URL |
| 400 | `BATCH_TOO_LARGE` | Plus de 500 articles, soit plus de 10 en mode test | Non, divisez le lot |
| 402 | `ASYNC_NEEDS_CREDITS` | Les tâches asynchrones et les traitements par lots utilisent les crédits achetés | Non, achetez des crédits ou utilisez la requête `POST /generate` |
| 429 | `TOO_MANY_JOBS` | 50 tâches asynchrones sont déjà en cours d'exécution sur le compte | Oui, après `Retry-After` |
| 500 | `JOB_CREATE_FAILED`, `BATCH_CREATE_FAILED` | Impossible de le créer. Crédits remboursés | Oui |

Une tâche qui échoue après avoir été acceptée renvoie le code d'erreur `error.code`, tant au niveau de la tâche que dans le webhook `generation.failed` : `CONTENT_FILTERED`, `GENERATION_FAILED` ou `INPUT_FETCH_FAILED` (impossible de télécharger l'URL d'une image). Le crédit correspondant est remboursé. Les éléments du lot annulés affichent le statut `CANCELLED`.

## Autres critères d'évaluation

| Point d'extrémité | HTTP | code | Réessayer ? |
|---|---|---|---|
| `GET /credits` | 500 | `CREDITS_UNAVAILABLE` | Oui |
| `GET /results/:id` | 404 | `NOT_FOUND` (inconnu, ne vous appartient pas ou date de plus de 7 jours) | Non |
| `DELETE /customers/:id` | 500 | `DELETE_FAILED` (rien n'a été supprimé) | Oui |
| `DELETE /results/:id` | 404 | `NOT_FOUND` | Non |
| `DELETE /results/:id` | 500 | `DELETE_FAILED` | Oui |

## Consignes d'utilisation recommandées

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

> **Avertissement :** ne réessayez jamais une erreur `402` dans une boucle. Cela signifie que le compte n'a plus de crédits.
