# Fehler

Jeder Fehler ist ein JSON-Objekt mit einer für Menschen lesbaren `error`-Meldung und einem stabilen `code`. Die Verzweigung sollte anhand des `code` erfolgen, nicht anhand der Meldung.

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

## Fehler erzeugen

| HTTP | Code | Was ist passiert? | Noch einmal versuchen? |
|---|---|---|---|
| 400 | `BAD_INPUT` | Der Text konnte nicht gelesen werden | Nein, korrigiere die Anfrage. |
| 400 | `NO_PERSON` | Personenbild fehlt, ist unlesbar oder hat ein nicht unterstütztes Format | Nein, bitte sende ein gültiges Bild |
| 400 | `NO_GARMENT` | Das Bild des Kleidungsstücks fehlt, ist unlesbar oder die `garment_url`-Adresse ist gesperrt | Nein, bitte sende ein gültiges Bild oder eine öffentliche https-URL |
| 401 | `NO_KEY` | Kein `X-API-KEY`-Header | Nein |
| 401 | `INVALID_KEY` | Schlüssel falsch oder widerrufen | Nein, schau mal nach dem Schlüssel im Armaturenbrett. |
| 402 | `NO_CREDITS` | Gekaufte Credits aufgebraucht | Nein, [Credits kaufen](/pricing#developer-api) |
| 402 | `QUOTA_EXCEEDED` | Freigrenze ausgeschöpft | Nein, Credits kaufen |
| 402 | `KEY_LIMIT_REACHED` | Dieser API-Schlüssel hat sein monatliches Guthabenlimit erreicht. Der Textkörper enthält die Felder `used` und `limit` | Nein, warte bis zum 1. (UTC) oder verwende einen Schlüssel mit einem höheren Limit |
| 402 | `FREE_TRIAL_USED` | Die kostenlose Testversion wurde auf diesem Gerät bereits genutzt. | Nein, Credits kaufen |
| 403 | `DEVICE_BANNED` | Dieses Gerät wurde wegen Missbrauchs gesperrt | Nein, wenden Sie sich an den Support |
| 400 | `BAD_IDEMPOTENCY_KEY` | Der `Idempotency-Key` ist leer, zu lang oder enthält Leerzeichen. | Nein, korrigiere die Kopfzeile. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | Eine Anfrage mit diesem Schlüssel wird noch bearbeitet. Es fallen keine Kosten an. | Ja, nach `Retry-After` |
| 409 | `IDEMPOTENCY_REPLAY` | Dieser Schlüssel hat bereits funktioniert. Es wurde nichts berechnet. | Nein, in der ersten Antwort war das Bild enthalten. |
| 409 | `IDEMPOTENCY_MISMATCH` | Dieser Schlüssel wurde mit verschiedenen Bildern verwendet | Nein, benutze einen neuen Schlüssel. |
| 413 | `IMAGE_TOO_LARGE` | Ein Bild ist größer als 15 MB | Nein, erst verkleinern |
| 422 | `CONTENT_FILTERED` | Durch die Inhaltsmoderation gesperrt. Guthaben zurückerstattet | Nein, verwende andere Bilder |
| 429 | `RATE_LIMITED` | Zu viele Anfragen | Ja, nach `Retry-After` Sekunden |
| 500 | `GENERATION_FAILED` | Der Motor ist ausgefallen. Der Kaufpreis wurde erstattet. | Ja, einmal |

## Asynchrone Aufträge und Stapelverarbeitung

| HTTP | Code | Was ist passiert? | Noch einmal versuchen? |
|---|---|---|---|
| 400 | `BAD_WEBHOOK_URL` | `webhook_url` ist keine öffentliche `https`-URL | Nein, korrigiere die URL |
| 400 | `BATCH_TOO_LARGE` | Mehr als 500 Artikel bzw. mehr als 10 im Testmodus | Nein, teile den Batch auf |
| 402 | `ASYNC_NEEDS_CREDITS` | Asynchrone Aufträge und Stapelverarbeitungen verbrauchen gekaufte Guthaben | Nein, kaufe Credits oder verwende `POST /generate` |
| 429 | `TOO_MANY_JOBS` | Auf dem Konto laufen bereits 50 asynchrone Jobs | Ja, nach `Retry-After` |
| 500 | `JOB_CREATE_FAILED`, `BATCH_CREATE_FAILED` | Konnte nicht erstellt werden. Guthaben zurückerstattet | Ja |

Ein Auftrag, der nach seiner Annahme fehlschlägt, meldet im Auftrag selbst und im Webhook `generation.failed` den Fehlercode `error.code`: `CONTENT_FILTERED`, `GENERATION_FAILED` oder `INPUT_FETCH_FAILED` (eine Bild-URL konnte nicht heruntergeladen werden). Das Guthaben wird zurückerstattet. Stornierte Batch-Elemente werden mit `CANCELLED` angezeigt.

## Weitere Endpunkte

| Endpunkt | HTTP | Code | Noch einmal versuchen? |
|---|---|---|---|
| `GET /credits` | 500 | `CREDITS_UNAVAILABLE` | Ja |
| `GET /results/:id` | 404 | `NOT_FOUND` (unbekannt, gehört nicht Ihnen oder ist älter als 7 Tage) | Nein |
| `DELETE /customers/:id` | 500 | `DELETE_FAILED` (es wurde nichts gelöscht) | Ja |
| `DELETE /results/:id` | 404 | `NOT_FOUND` | Nein |
| `DELETE /results/:id` | 500 | `DELETE_FAILED` | Ja |

## Empfohlene Handhabung

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

> **Warnung:** Versuchen Sie niemals, einen `402`-Fehler in einer Schleife erneut abzufragen. Dies bedeutet, dass das Guthaben des Kontos aufgebraucht ist.
