# Errors

Every error is JSON with a human-readable `error` and a stable `code`. Branch on `code`, not on the message.

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

## Generate errors

| HTTP | code | What happened | Retry? |
|---|---|---|---|
| 400 | `BAD_INPUT` | The body could not be read | No, fix the request |
| 400 | `NO_PERSON` | Person image missing, unreadable or not a supported format | No, send a valid image |
| 400 | `NO_GARMENT` | Garment image missing, unreadable, or `garment_url` blocked | No, send a valid image or public https URL |
| 401 | `NO_KEY` | No `X-API-KEY` header | No |
| 401 | `INVALID_KEY` | Key wrong or revoked | No, check the key in the dashboard |
| 402 | `NO_CREDITS` | Purchased credits used up | No, [buy credits](/pricing#developer-api) |
| 402 | `QUOTA_EXCEEDED` | Free allowance used up | No, buy credits |
| 402 | `KEY_LIMIT_REACHED` | This API key reached its monthly credit limit. The body includes `used` and `limit` | No, wait for the 1st (UTC) or use a key with a higher limit |
| 402 | `FREE_TRIAL_USED` | The free trial was already used on this device | No, buy credits |
| 403 | `DEVICE_BANNED` | This device is blocked for abuse | No, contact support |
| 400 | `BAD_IDEMPOTENCY_KEY` | `Idempotency-Key` is empty, too long or has spaces | No, fix the header |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this key is still running. Nothing charged | Yes, after `Retry-After` |
| 409 | `IDEMPOTENCY_REPLAY` | This key already succeeded. Nothing charged | No, the first response had the image |
| 409 | `IDEMPOTENCY_MISMATCH` | This key was used with different images | No, use a new key |
| 413 | `IMAGE_TOO_LARGE` | An image is over 15MB | No, downscale first |
| 422 | `CONTENT_FILTERED` | Blocked by content moderation. Credit refunded | No, use different images |
| 429 | `RATE_LIMITED` | Too many requests | Yes, after `Retry-After` seconds |
| 500 | `GENERATION_FAILED` | The engine failed. Credit refunded | Yes, once |

## Async jobs and batches

| HTTP | code | What happened | Retry? |
|---|---|---|---|
| 400 | `BAD_WEBHOOK_URL` | `webhook_url` is not a public `https` URL | No, fix the URL |
| 400 | `BATCH_TOO_LARGE` | More than 500 items, or more than 10 in test mode | No, split the batch |
| 402 | `ASYNC_NEEDS_CREDITS` | Async jobs and batches use purchased credits | No, buy credits or use `POST /generate` |
| 429 | `TOO_MANY_JOBS` | 50 async jobs already running on the account | Yes, after `Retry-After` |
| 500 | `JOB_CREATE_FAILED`, `BATCH_CREATE_FAILED` | Could not create it. Credits refunded | Yes |

A job that fails after it was accepted reports `error.code` on the job and in the `generation.failed` webhook: `CONTENT_FILTERED`, `GENERATION_FAILED` or `INPUT_FETCH_FAILED` (an image URL could not be downloaded). Its credit is refunded. Cancelled batch items show `CANCELLED`.

## Other endpoints

| Endpoint | HTTP | code | Retry? |
|---|---|---|---|
| `GET /credits` | 500 | `CREDITS_UNAVAILABLE` | Yes |
| `GET /results/:id` | 404 | `NOT_FOUND` (unknown, not yours, or older than 7 days) | No |
| `DELETE /customers/:id` | 500 | `DELETE_FAILED` (nothing was cleared) | Yes |
| `DELETE /results/:id` | 404 | `NOT_FOUND` | No |
| `DELETE /results/:id` | 500 | `DELETE_FAILED` | Yes |

## Recommended handling

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

> **Warning:** Never retry a `402` in a loop. It means the account is out of credits.
