API reference
Errors
Every error code, what it means and whether to retry.
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 |
| 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.