Search docs

Search the TryOnCloud API docs

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

HTTPcodiceCosa è successoRiprovare?
400BAD_INPUTNon è stato possibile leggere il corpoNo, correggi la richiesta
400NO_PERSONL'immagine della persona manca, è illeggibile o non è in un formato supportatoNo, invia un'immagine valida
400NO_GARMENTL'immagine del capo è mancante, illeggibile o l'garment_url è bloccatoNo, invia un'immagine valida o un URL https pubblico
401NO_KEYAssenza dell'intestazione X-API-KEYNo
401INVALID_KEYCodice errato o revocatoNo, controlla la chiave nel cruscotto
402NO_CREDITSCrediti acquistati esauritiNo, acquista crediti
402QUOTA_EXCEEDEDLa quota gratuita è esauritaNo, acquista crediti
402KEY_LIMIT_REACHEDQuesta chiave API ha raggiunto il limite di credito mensile. Il corpo del messaggio include i campi used e limitNo, aspetta il 1° (UTC) oppure usa una chiave con un limite più alto
402FREE_TRIAL_USEDLa versione di prova gratuita è già stata utilizzata su questo dispositivoNo, acquista crediti
403DEVICE_BANNEDQuesto dispositivo è stato bloccato a causa di un uso improprioNo, contatta l'assistenza
400BAD_IDEMPOTENCY_KEYIdempotency-Key è vuoto, troppo lungo o contiene spaziNo, correggi l'intestazione
409IDEMPOTENCY_IN_PROGRESSUna richiesta con questa chiave è ancora in esecuzione. Nessun addebitoSì, dopo Retry-After
409IDEMPOTENCY_REPLAYQuesta chiave ha già funzionato. Non è stato addebitato alcun importo.No, la prima risposta conteneva l'immagine
409IDEMPOTENCY_MISMATCHQuesta chiave è stata utilizzata con immagini diverseNo, usa una nuova chiave
413IMAGE_TOO_LARGEUn'immagine supera i 15 MBNo, prima riduci la scala
422CONTENT_FILTEREDBloccato a causa della moderazione dei contenuti. Credito rimborsatoNo, usa immagini diverse
429RATE_LIMITEDTroppe richiesteSì, dopo Retry-After secondi
500GENERATION_FAILEDIl motore si è guastato. Importo rimborsatoSì, una volta

Operazioni asincrone e elaborazioni in batch

HTTPcodiceCosa è successoRiprovare?
400BAD_WEBHOOK_URLwebhook_url non è un URL https pubblicoNo, correggi l'URL
400BATCH_TOO_LARGEOltre 500 articoli, ovvero più di 10 in modalità di provaNo, dividi il lotto
402ASYNC_NEEDS_CREDITSI lavori asincroni e i batch utilizzano i crediti acquistatiNo, acquista crediti oppure usa POST /generate
429TOO_MANY_JOBS50 processi asincroni già in esecuzione sull'accountSì, dopo Retry-After
500JOB_CREATE_FAILED, BATCH_CREATE_FAILEDImpossibile crearlo. Crediti rimborsatiSì

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

EndpointHTTPcodiceRiprovare?
GET /credits500CREDITS_UNAVAILABLESì
GET /results/:id404NOT_FOUND (sconosciuto, non tuo o risalente a più di 7 giorni fa)No
DELETE /customers/:id500DELETE_FAILED (non è stato cancellato nulla)Sì
DELETE /results/:id404NOT_FOUNDNo
DELETE /results/:id500DELETE_FAILEDSì

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.