API-Referenz
Fehler
Jeder Fehlercode, was er bedeutet und ob ein erneuter Versuch unternommen werden sollte.
Code-Beispiele, Endpunkte und Fehlercodes sind in jeder Sprache identisch.
Jeder Fehler ist ein JSON-Objekt mit einer für Menschen lesbaren error-Meldung und einem stabilen code. Die Verzweigung sollte anhand des code erfolgen, nicht anhand der Meldung.
json
{ "error": "No credits left. Top up your developer wallet to continue.", "code": "NO_CREDITS" }Fehler erzeugen
| HTTP | Code | Was ist passiert? | Noch einmal versuchen? |
|---|---|---|---|
| 400 | BAD_INPUT | Der Text konnte nicht gelesen werden | Nein, korrigiere die Anfrage. |
| 400 | NO_PERSON | Personenbild fehlt, ist unlesbar oder hat ein nicht unterstütztes Format | Nein, bitte sende ein gültiges Bild |
| 400 | NO_GARMENT | Das Bild des Kleidungsstücks fehlt, ist unlesbar oder die garment_url-Adresse ist gesperrt | Nein, bitte sende ein gültiges Bild oder eine öffentliche https-URL |
| 401 | NO_KEY | Kein X-API-KEY-Header | Nein |
| 401 | INVALID_KEY | Schlüssel falsch oder widerrufen | Nein, schau mal nach dem Schlüssel im Armaturenbrett. |
| 402 | NO_CREDITS | Gekaufte Credits aufgebraucht | Nein, Credits kaufen |
| 402 | QUOTA_EXCEEDED | Freigrenze ausgeschöpft | Nein, Credits kaufen |
| 402 | KEY_LIMIT_REACHED | Dieser API-Schlüssel hat sein monatliches Guthabenlimit erreicht. Der Textkörper enthält die Felder used und limit | Nein, warte bis zum 1. (UTC) oder verwende einen Schlüssel mit einem höheren Limit |
| 402 | FREE_TRIAL_USED | Die kostenlose Testversion wurde auf diesem Gerät bereits genutzt. | Nein, Credits kaufen |
| 403 | DEVICE_BANNED | Dieses Gerät wurde wegen Missbrauchs gesperrt | Nein, wenden Sie sich an den Support |
| 400 | BAD_IDEMPOTENCY_KEY | Der Idempotency-Key ist leer, zu lang oder enthält Leerzeichen. | Nein, korrigiere die Kopfzeile. |
| 409 | IDEMPOTENCY_IN_PROGRESS | Eine Anfrage mit diesem Schlüssel wird noch bearbeitet. Es fallen keine Kosten an. | Ja, nach Retry-After |
| 409 | IDEMPOTENCY_REPLAY | Dieser Schlüssel hat bereits funktioniert. Es wurde nichts berechnet. | Nein, in der ersten Antwort war das Bild enthalten. |
| 409 | IDEMPOTENCY_MISMATCH | Dieser Schlüssel wurde mit verschiedenen Bildern verwendet | Nein, benutze einen neuen Schlüssel. |
| 413 | IMAGE_TOO_LARGE | Ein Bild ist größer als 15 MB | Nein, erst verkleinern |
| 422 | CONTENT_FILTERED | Durch die Inhaltsmoderation gesperrt. Guthaben zurückerstattet | Nein, verwende andere Bilder |
| 429 | RATE_LIMITED | Zu viele Anfragen | Ja, nach Retry-After Sekunden |
| 500 | GENERATION_FAILED | Der Motor ist ausgefallen. Der Kaufpreis wurde erstattet. | Ja, einmal |
Asynchrone Aufträge und Stapelverarbeitung
| HTTP | Code | Was ist passiert? | Noch einmal versuchen? |
|---|---|---|---|
| 400 | BAD_WEBHOOK_URL | webhook_url ist keine öffentliche https-URL | Nein, korrigiere die URL |
| 400 | BATCH_TOO_LARGE | Mehr als 500 Artikel bzw. mehr als 10 im Testmodus | Nein, teile den Batch auf |
| 402 | ASYNC_NEEDS_CREDITS | Asynchrone Aufträge und Stapelverarbeitungen verbrauchen gekaufte Guthaben | Nein, kaufe Credits oder verwende POST /generate |
| 429 | TOO_MANY_JOBS | Auf dem Konto laufen bereits 50 asynchrone Jobs | Ja, nach Retry-After |
| 500 | JOB_CREATE_FAILED, BATCH_CREATE_FAILED | Konnte nicht erstellt werden. Guthaben zurückerstattet | Ja |
Ein Auftrag, der nach seiner Annahme fehlschlägt, meldet im Auftrag selbst und im Webhook generation.failed den Fehlercode error.code: CONTENT_FILTERED, GENERATION_FAILED oder INPUT_FETCH_FAILED (eine Bild-URL konnte nicht heruntergeladen werden). Das Guthaben wird zurückerstattet. Stornierte Batch-Elemente werden mit CANCELLED angezeigt.
Weitere Endpunkte
| Endpunkt | HTTP | Code | Noch einmal versuchen? |
|---|---|---|---|
GET /credits | 500 | CREDITS_UNAVAILABLE | Ja |
GET /results/:id | 404 | NOT_FOUND (unbekannt, gehört nicht Ihnen oder ist älter als 7 Tage) | Nein |
DELETE /customers/:id | 500 | DELETE_FAILED (es wurde nichts gelöscht) | Ja |
DELETE /results/:id | 404 | NOT_FOUND | Nein |
DELETE /results/:id | 500 | DELETE_FAILED | Ja |
Empfohlene Handhabung
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")
}Warnung: Versuchen Sie niemals, einen
402-Fehler in einer Schleife erneut abzufragen. Dies bedeutet, dass das Guthaben des Kontos aufgebraucht ist.