API-Referenz
Fehler
Fehlerstruktur, alle Fehlercodes und Hinweise zum Wiederholen von Anfragen.
Fehlerstruktur#
{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Not enough credits.",
"request_id": "a698a9af-0685-4557-9b29-ca57637748f9",
"details": { "top_up_url": "https://scifig.ai/pricing?utm_source=api" }
}
}Verzweigen Sie anhand von error.code und details.reason, niemals anhand von message, da sich dieser Text ändern kann. Antworten enthalten keine internen Diagnosedaten.
Codes#
| Code | HTTP | Bedeutung | Erneut versuchen |
|---|---|---|---|
| UNAUTHORIZED | 401 | Zugangsdaten fehlen oder sind ungültig. | Nein; Anfrage ändern oder einen neuen Schlüssel verwenden |
| ACCOUNT_UNAVAILABLE | 401 | Dieses Konto kann die API nicht verwenden. | Nein; Anfrage ändern oder einen neuen Schlüssel verwenden |
| SCOPE_DENIED | 403 | Die Zugangsdaten gewähren diese Berechtigung nicht. | Nein; Anfrage ändern oder einen neuen Schlüssel verwenden |
| INVALID_REQUEST | 400 | Die Anfrage ist ungültig. | Nein; Anfrage ändern oder einen neuen Schlüssel verwenden |
| IDEMPOTENCY_KEY_REQUIRED | 400 | Ein Idempotency-Key-Header mit 1–255 sichtbaren ASCII-Zeichen ist erforderlich. | Nein; Anfrage ändern oder einen neuen Schlüssel verwenden |
| IDEMPOTENCY_CONFLICT | 409 | Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet. | Nein; Anfrage ändern oder einen neuen Schlüssel verwenden |
| IDEMPOTENCY_IN_PROGRESS | 409 | Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet. | Ja, mit demselben Idempotency-Key |
| NOT_FOUND | 404 | Nicht gefunden. | Nein; Anfrage ändern oder einen neuen Schlüssel verwenden |
| REVISION_CONFLICT | 409 | Der Diagramm- oder Flussdiagrammauftrag kann derzeit nicht bearbeitet werden: NOT_LATEST_REVISION, EDIT_IN_PROGRESS oder PARENT_JOB_RUNNING, solange der übergeordnete Auftrag noch läuft. | Nur bei PARENT_JOB_RUNNING: nach Retry-After mit demselben Schlüssel. Andernfalls die neueste Version mit einem neuen Schlüssel bearbeiten |
| PAYLOAD_TOO_LARGE | 413 | Der Anfrageinhalt ist zu groß. | Nein; Anfrage ändern oder einen neuen Schlüssel verwenden |
| INSUFFICIENT_CREDITS | 402 | Nicht genügend Credits. | Nein; Anfrage ändern oder einen neuen Schlüssel verwenden |
| CONTENT_REJECTED | 422 | Die Inhaltsrichtlinie hat die Anfrage abgelehnt. Dies wird beim Erstellen der Anfrage als 422 zurückgegeben oder als error.code eines fehlgeschlagenen Auftrags, wenn es während der Ausführung geschieht; in beiden Fällen werden die Credits erstattet. | Nein; Beschreibung oder Eingabe ändern und einen neuen Schlüssel verwenden |
| PLAN_REQUIRED | 403 | Ihr Tarif enthält diese Option nicht. | Nein; Anfrage ändern oder einen neuen Schlüssel verwenden |
| RATE_LIMITED | 429 | Zu viele Anfragen, Aufgaben pro Stunde, Konvertierungen pro Tag oder Uploads; details.reason nennt den Grund. | Ja, mit demselben Idempotency-Key |
| CONCURRENCY_LIMITED | 429 | Für dieses Konto laufen zu viele Aufgaben. | Ja, mit demselben Idempotency-Key |
| SERVICE_UNAVAILABLE | 503 | Der Dienst ist vorübergehend nicht verfügbar. Wiederholen Sie die Anfrage mit demselben Idempotency-Key. | Ja, mit demselben Idempotency-Key |
| TASK_FAILED | 502 | Die Aufgabe ist fehlgeschlagen und ihre Credits wurden erstattet. Senden Sie zum erneuten Versuch eine neue Anfrage mit einem neuen Idempotency-Key. | Nein; Anfrage ändern oder einen neuen Schlüssel verwenden |
| INTERNAL_ERROR | 500 | Interner Fehler. | Ja, mit demselben Idempotency-Key |
INVALID_REQUEST kann, sofern verfügbar, details.reason, details.field oder details.issues enthalten. Anfrageinhalte oberhalb des Limits von 256 KB für JSON bzw. des jeweiligen Dateilimits für Uploads führen zu 413 PAYLOAD_TOO_LARGE. Nur INSUFFICIENT_CREDITS enthält details.top_up_url. Wenn eine Erstellungsanfrage nach dem Erstellen ihres Auftrags fehlschlägt (429, 503, 409 IDEMPOTENCY_IN_PROGRESS oder 500 INTERNAL_ERROR), nennt details.job_id diesen Auftrag: Wiederholen Sie die Anfrage mit demselben Idempotency-Key oder fragen Sie GET /jobs/{job_id} ab; verwenden Sie niemals einen neuen Schlüssel.
Codes in einem fehlgeschlagenen Auftrag#
Ein erstellter und anschließend fehlgeschlagener Auftrag meldet status: "failed" und ein error-Objekt. Neben den obigen Codes für abgelehnte Anfragen kann error.code diese Werte haben:
| error.code | Bedeutung | Vorgehen |
|---|---|---|
| TASK_TIMED_OUT | Die Aufgabe hat ihr Zeitlimit überschritten und die Credits wurden erstattet. Eine Illustrationsgenerierung oder -bearbeitung kann late_delivery_until enthalten: Bis dahin kann das Ergebnis noch kostenlos eintreffen. | Fragen Sie den Auftrag bis late_delivery_until weiter ab; senden Sie andernfalls eine neue Anfrage mit einem neuen Schlüssel |
| CONTENT_REJECTED | Die Inhaltsrichtlinie hat das Ergebnis während der Ausführung abgelehnt; die Credits wurden erstattet. Derselbe Code wird als 422 zurückgegeben, wenn die Anfrage selbst bei der Erstellung abgelehnt wird. | Ändern Sie die Beschreibung oder Eingabe und verwenden Sie einen neuen Schlüssel |
| ADMISSION_INCOMPLETE | Der Auftrag wurde nie gestartet, da ein wiederholbarer Fehler ihn verhindert hat. Es wurden keine Credits verbraucht. | Senden Sie dieselbe Anfrage mit demselben Idempotency-Key |
| TASK_NOT_FOUND | Der Auftrag wurde angenommen, aber seine Aufgabe ist nicht mehr auffindbar. | Senden Sie eine neue Anfrage mit einem neuen Schlüssel |
| TASK_FAILED | Die Aufgabe ist fehlgeschlagen und die Credits wurden erstattet. Jeder Engine-Fehler ohne eigenen öffentlichen Code wird zu TASK_FAILED; der Engine-Code steht in details.reason. | Senden Sie eine neue Anfrage mit einem neuen Schlüssel |
| INTERNAL_ERROR | Die Aufgabe ist ohne Angabe eines Grundes fehlgeschlagen; die Credits wurden erstattet. | Senden Sie eine neue Anfrage mit einem neuen Schlüssel |
Ursachen für 429#
- Zu viele Anfragen: 20 Erstellungsanfragen pro Minute und Zugangsdaten, 40 pro Konto, 120 Leseanfragen pro Minute und Zugangsdaten.
Retry-Aftergibt die Zeit bis zum Zurücksetzen des Zeitfensters an;details.reasonist nicht vorhanden. - In der letzten Stunde wurden zu viele Aufgaben gestartet: höchstens 200 pro Konto, gemeinsam mit der Website.
Retry-After: 30. - Zu viele Aufgaben laufen gleichzeitig:
429 CONCURRENCY_LIMITED, je nach Tarif und gemeinsam mit der Website; sieheGET /credits.Retry-After: 30. - Das Tageskontingent von 200 kostenlosen PNG-, PDF-, TIFF- und PPTX-Konvertierungen ist ausgeschöpft:
details.reason = DAILY_CONVERSION_LIMIT,Retry-Afterbis zum Zurücksetzen des Tagesfensters. - Uploads erfolgen zu schnell:
details.reason = UPLOAD_RATE_LIMITEDfür Bilder und Masken anPOST /files, Flussdiagrammanhänge und Diagrammdaten. Es gilt das Uploadlimit pro Minute der Website. - Zu viele Uploads an einem Tag:
details.reason = UPLOAD_DAILY_LIMIT_REACHEDfür Flussdiagrammanhänge und Diagrammdaten. Es gilt das tägliche Uploadlimit der Website. - Texterkennungen: 20 je 15 Minuten und Konto, gemeinsam mit der Website.