Search docs

Search the TryOnCloud API docs

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

HTTPcodeWhat happenedRetry?
400BAD_INPUTThe body could not be readNo, fix the request
400NO_PERSONPerson image missing, unreadable or not a supported formatNo, send a valid image
400NO_GARMENTGarment image missing, unreadable, or garment_url blockedNo, send a valid image or public https URL
401NO_KEYNo X-API-KEY headerNo
401INVALID_KEYKey wrong or revokedNo, check the key in the dashboard
402NO_CREDITSPurchased credits used upNo, buy credits
402QUOTA_EXCEEDEDFree allowance used upNo, buy credits
402KEY_LIMIT_REACHEDThis API key reached its monthly credit limit. The body includes used and limitNo, wait for the 1st (UTC) or use a key with a higher limit
402FREE_TRIAL_USEDThe free trial was already used on this deviceNo, buy credits
403DEVICE_BANNEDThis device is blocked for abuseNo, contact support
400BAD_IDEMPOTENCY_KEYIdempotency-Key is empty, too long or has spacesNo, fix the header
409IDEMPOTENCY_IN_PROGRESSA request with this key is still running. Nothing chargedYes, after Retry-After
409IDEMPOTENCY_REPLAYThis key already succeeded. Nothing chargedNo, the first response had the image
409IDEMPOTENCY_MISMATCHThis key was used with different imagesNo, use a new key
413IMAGE_TOO_LARGEAn image is over 15MBNo, downscale first
422CONTENT_FILTEREDBlocked by content moderation. Credit refundedNo, use different images
429RATE_LIMITEDToo many requestsYes, after Retry-After seconds
500GENERATION_FAILEDThe engine failed. Credit refundedYes, once

Async jobs and batches

HTTPcodeWhat happenedRetry?
400BAD_WEBHOOK_URLwebhook_url is not a public https URLNo, fix the URL
400BATCH_TOO_LARGEMore than 500 items, or more than 10 in test modeNo, split the batch
402ASYNC_NEEDS_CREDITSAsync jobs and batches use purchased creditsNo, buy credits or use POST /generate
429TOO_MANY_JOBS50 async jobs already running on the accountYes, after Retry-After
500JOB_CREATE_FAILED, BATCH_CREATE_FAILEDCould not create it. Credits refundedYes

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

EndpointHTTPcodeRetry?
GET /credits500CREDITS_UNAVAILABLEYes
GET /results/:id404NOT_FOUND (unknown, not yours, or older than 7 days)No
DELETE /customers/:id500DELETE_FAILED (nothing was cleared)Yes
DELETE /results/:id404NOT_FOUNDNo
DELETE /results/:id500DELETE_FAILEDYes
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.