Riferimento API
Errori
Ogni codice di errore, il suo significato e se è il caso di riprovare.
Gli esempi di codice, gli endpoint e i codici di errore sono gli stessi in ogni linguaggio.
Ogni errore è in formato JSON con un campo error leggibile dall'utente e un campo code stabile. Creare un ramo in base al campo code, non al messaggio.
json
{ "error": "No credits left. Top up your developer wallet to continue.", "code": "NO_CREDITS" }Genera errori
| HTTP | codice | Cosa è successo | Riprovare? |
|---|---|---|---|
| 400 | BAD_INPUT | Non è stato possibile leggere il corpo | No, correggi la richiesta |
| 400 | NO_PERSON | L'immagine della persona manca, è illeggibile o non è in un formato supportato | No, invia un'immagine valida |
| 400 | NO_GARMENT | L'immagine del capo è mancante, illeggibile o l'garment_url è bloccato | No, invia un'immagine valida o un URL https pubblico |
| 401 | NO_KEY | Assenza dell'intestazione X-API-KEY | No |
| 401 | INVALID_KEY | Codice errato o revocato | No, controlla la chiave nel cruscotto |
| 402 | NO_CREDITS | Crediti acquistati esauriti | No, acquista crediti |
| 402 | QUOTA_EXCEEDED | La quota gratuita è esaurita | No, acquista crediti |
| 402 | KEY_LIMIT_REACHED | Questa chiave API ha raggiunto il limite di credito mensile. Il corpo del messaggio include i campi used e limit | No, aspetta il 1° (UTC) oppure usa una chiave con un limite più alto |
| 402 | FREE_TRIAL_USED | La versione di prova gratuita è già stata utilizzata su questo dispositivo | No, acquista crediti |
| 403 | DEVICE_BANNED | Questo dispositivo è stato bloccato a causa di un uso improprio | No, contatta l'assistenza |
| 400 | BAD_IDEMPOTENCY_KEY | Idempotency-Key è vuoto, troppo lungo o contiene spazi | No, correggi l'intestazione |
| 409 | IDEMPOTENCY_IN_PROGRESS | Una richiesta con questa chiave è ancora in esecuzione. Nessun addebito | Sì, dopo Retry-After |
| 409 | IDEMPOTENCY_REPLAY | Questa chiave ha già funzionato. Non è stato addebitato alcun importo. | No, la prima risposta conteneva l'immagine |
| 409 | IDEMPOTENCY_MISMATCH | Questa chiave è stata utilizzata con immagini diverse | No, usa una nuova chiave |
| 413 | IMAGE_TOO_LARGE | Un'immagine supera i 15 MB | No, prima riduci la scala |
| 422 | CONTENT_FILTERED | Bloccato a causa della moderazione dei contenuti. Credito rimborsato | No, usa immagini diverse |
| 429 | RATE_LIMITED | Troppe richieste | Sì, dopo Retry-After secondi |
| 500 | GENERATION_FAILED | Il motore si è guastato. Importo rimborsato | Sì, una volta |
Operazioni asincrone e elaborazioni in batch
| HTTP | codice | Cosa è successo | Riprovare? |
|---|---|---|---|
| 400 | BAD_WEBHOOK_URL | webhook_url non è un URL https pubblico | No, correggi l'URL |
| 400 | BATCH_TOO_LARGE | Oltre 500 articoli, ovvero più di 10 in modalità di prova | No, dividi il lotto |
| 402 | ASYNC_NEEDS_CREDITS | I lavori asincroni e i batch utilizzano i crediti acquistati | No, acquista crediti oppure usa POST /generate |
| 429 | TOO_MANY_JOBS | 50 processi asincroni già in esecuzione sull'account | Sì, dopo Retry-After |
| 500 | JOB_CREATE_FAILED, BATCH_CREATE_FAILED | Impossibile crearlo. Crediti rimborsati | Sì |
Un’attività che fallisce dopo essere stata accettata riporta il codice error.code sia nell’attività stessa che nel webhook generation.failed: CONTENT_FILTERED, GENERATION_FAILED o INPUT_FETCH_FAILED (impossibile scaricare l’URL di un’immagine). Il credito corrispondente viene rimborsato. Le voci del batch annullate mostrano lo stato CANCELLED.
Altri endpoint
| Endpoint | HTTP | codice | Riprovare? |
|---|---|---|---|
GET /credits | 500 | CREDITS_UNAVAILABLE | Sì |
GET /results/:id | 404 | NOT_FOUND (sconosciuto, non tuo o risalente a più di 7 giorni fa) | No |
DELETE /customers/:id | 500 | DELETE_FAILED (non è stato cancellato nulla) | Sì |
DELETE /results/:id | 404 | NOT_FOUND | No |
DELETE /results/:id | 500 | DELETE_FAILED | Sì |
Istruzioni per l'uso consigliate
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")
}Avviso: non riprovare mai con un codice
402 in un ciclo. Significa che l'account ha esaurito i crediti.