Fehlerbehebung und Wiederherstellung

Jeder Abschnitt unten beginnt mit dem, was Sie sehen, erklärt die übliche Ursache und sagt Ihnen, was zu tun ist. Die vollständige Bedeutung jeder Fehlernummer steht unter Fehler; diese Seite beantwortet die Frage „Und was jetzt?“.

Ihr Problem finden

Nützliche Belege sichern

Schreiben Sie auf, was passiert ist, bevor Sie irgendetwas ändern. Das beschleunigt jeden der folgenden Schritte, und genau das braucht der Support:

• Die Uhrzeit, wenn möglich in UTC.
• Den Endpunkt, den Sie aufgerufen haben, zum Beispiel POST /api/v1/jobs/createTask.
• Den HTTP-Status und den code aus dem Antwort-Body.
• Die request_id: Sie steht im Antwort-Body und im Antwort-Header X-Request-Id.
• Die Task-ID, falls Sie eine erhalten haben. Sie beginnt mit job_ und steht außerdem in der Konsole auf der Seite Logs.

Halten Sie drei Situationen auseinander, denn sie verlangen unterschiedliches Vorgehen: Die API hat die Anfrage ausdrücklich abgelehnt (Sie haben einen JSON-Fehler erhalten; es wurde nichts angelegt und nichts berechnet), Sie haben überhaupt keine Antwort erhalten (ein Timeout oder eine abgebrochene Verbindung; der Task kann existieren, siehe unten), oder der Task wurde angenommen und ist später fehlgeschlagen (Sie haben eine Task-ID mit state: "failed").

Ist eine Antwort kein JSON, zum Beispiel eine HTML- oder Textseite, stammt sie aus unserem Edge-Netzwerk und hat die API nie erreicht. Notieren Sie den HTTP-Status und die ersten Zeilen des Bodys. Eine 403-Seite dieser Art bedeutet meist, dass die Anfrage aus einer Region kommt, die wir nicht bedienen können; ein erneuter Versuch ändert daran nichts.

Schreiben Sie niemals API-Schlüssel, Passwörter, vollständige Prompts oder Originaldateien in allgemeine Logs oder Supportanfragen.

Bezahlt, aber das Guthaben hat sich nicht geändert

• Karte: Das Guthaben ändert sich erst, wenn die Bestätigung des Zahlungsdienstleisters bei uns eingeht, meist innerhalb von Sekunden. Laden Sie Abrechnung neu und sehen Sie unter Aufladungen nach.
• Krypto: Das Guthaben wird gutgeschrieben, sobald das Netzwerk die Transaktion bestätigt hat, meist nach wenigen Minuten. Wer weniger als den angezeigten Betrag zahlt oder erst nach Ablauf der Bezahlseite zahlt, erhält keine automatische Gutschrift.
• Manuelle Überweisung: Öffnen Sie den Auftrag unter Aufladungen und senden Sie Ihre Bankreferenz oder den Transaktionshash. Wir prüfen das von Hand, meist innerhalb weniger Stunden.

Die vollständige Liste der Fälle steht unter Konto einrichten → Häufige Probleme. Fehlt das Geld immer noch? Starten Sie beim Support eine Unterhaltung (Thema Abrechnung) und nennen Sie die Auftrags-ID, bei Krypto zusätzlich den Transaktionshash. Senden Sie niemals Kartennummern oder Passwörter.

Jeder Aufruf liefert 401 oder 403

Beginnen Sie mit einem Aufruf, der nichts kostet und nichts verändert: dem Abfragen Ihres Guthabens.

echo "${SPICY_API_KEY:0:9}"
curl https://api.spicyapi.ai/api/v1/chat/credit \
  -H "Authorization: Bearer $SPICY_API_KEY"

Die erste Zeile sollte sk-spicy- ausgeben. Gibt sie nichts aus, ist der Schlüssel in diesem Terminal nicht geladen; setzen Sie ihn erneut (siehe Konto einrichten). Lesen Sie dann das Feld msg der Antwort:

Keiner dieser Fehler verschwindet durch Wiederholen.

Guthaben, Limits und Support

• 40201: Das verfügbare Guthaben deckt den geschätzten Preis des Tasks nicht. Laden Sie Guthaben auf (siehe Konto einrichten) und senden Sie danach dieselbe Anfrage mit demselben Idempotency-Key erneut. Bonusguthaben aus einer Aktion bezahlt nur die Modelle, für die es gilt.
• 40202: Ein Ausgabenlimit ist erreicht; msg sagt, welches. Ein Schlüssellimit (This key has reached its …) erhöhen Sie unter API-Schlüssel → Bearbeiten, oder es beginnt von selbst neu (das Tageslimit um 00:00 UTC, das Monatslimit am 1. des Monats, das Gesamtlimit nie). Eine Teamgrenze (Workspace … budget has been reached) erhöht ein Inhaber, Admin oder Budgetverwalter auf der Seite Team. Das Plattformlimit (Platform quota for today is exhausted…) lässt sich nicht erhöhen; versuchen Sie es nach 00:00 UTC erneut. Siehe Abrechnung zu den Ausgabenlimits.
• 429: zu viele Anfragen. Warten Sie die Anzahl Sekunden aus Retry-After ab und verlangsamen Sie; am meisten hilft es, Webhooks statt enger Polling-Schleifen zu nutzen. Lautet die Meldung Too many pending uploads…, hilft Warten nicht: Schließen Sie die bereits begonnenen Uploads ab. Siehe Rate Limits.

Den Support kontaktieren: Starten Sie in der Konsole unter Support eine Unterhaltung, oder schreiben Sie an support@spicyapi.ai. Fügen Sie die Belege von oben bei: Uhrzeit, Endpunkt, code, request_id oder Task-ID, was Sie erwartet haben und was passiert ist, sowie den Aufbau Ihrer Anfrage ohne private Werte. Senden Sie niemals einen API-Schlüssel.

Modell fehlt oder ist nicht verfügbar

• Das Modell steht nicht in Ihrer Liste, oder Sie erhalten 404: Rufen Sie GET /api/v1/models mit Ihrem API-Schlüssel auf und verwenden Sie ein Modell, bei dem enabled und available beide true sind; kopieren Sie seine ID exakt. Eine Modellseite auf der Website beweist nicht, dass Ihr Schlüssel das Modell gerade aufrufen darf. Siehe Modellkatalog und Schemas.
• 50301: Das Modell kann im Moment keine Tasks annehmen. Versuchen Sie es einige Male mit wachsenden Pausen erneut und hören Sie dann auf; wiederholte Anfragen machen ein nicht verfügbares Modell nicht wieder verfügbar. Laden Sie den Katalog neu, und fragen Sie die Person, die bezahlt, bevor Sie zu einem anderen Modell wechseln.
• 40004: Das Modell funktioniert, aber nicht mit dieser Kombination von Einstellungen. msg nennt die Einstellung in Klammern. Ändern Sie diesen Wert (zum Beispiel eine Auflösung oder ein Seitenverhältnis), statt es erneut zu versuchen.
• 40301: Das Modell existiert, aber dieser Schlüssel darf es nicht verwenden; bearbeiten Sie die erlaubten Modelle des Schlüssels.

Ungültige Eingabe oder Konflikt mit der Kostenschätzung

• 400: Vergleichen Sie Ihren input mit dem aktuellen inputSchema des Modells im Katalog: Feldnamen, Typen, erlaubte Werte und bedingte Pflichtfelder. Entfernen Sie Felder, die das Modell nicht aufführt. Prüfen Sie nach einem Modellwechsel erneut, denn jedes Modell hat sein eigenes Schema.
• 40003: Eine hochgeladene Datei passt nicht zu dem, was Sie beim Anfordern ihrer Upload-URL angegeben haben. Fordern Sie eine neue Upload-URL mit dem richtigen contentType und der richtigen Größe an und laden Sie erneut hoch.
• 413: Der Anfrage-Body ist zu groß. Laden Sie Medien über den Upload-Ablauf hoch, statt sie einzubetten.
• 40901: Die Kostenschätzung ist abgelaufen, die Anfrage hat sich nach der Schätzung geändert, oder der Preis hat sich geändert. Holen Sie eine neue Kostenschätzung ein, zeigen Sie den neuen Betrag der Person, die bezahlt, und bestätigen Sie erneut. Siehe Kostenschätzungen.
• Anderer 409: Behandeln Sie ihn je nach Vorgang. Ein Idempotenzschlüssel, der bereits für einen anderen Inhalt verwendet wurde, braucht für die neue Anfrage einen neuen, korrekten Idempotency-Key, keine endlosen Wiederholungen. Siehe Fehler, wann sich ein erneuter Versuch nach 409 lohnt.

Timeout beim Absenden, keine Task-ID

Ein Timeout sagt Ihnen nicht, ob der Task angelegt wurde. Senden Sie die Anfrage nicht einfach mit einem neuen Idempotenzschlüssel erneut: Das kann einen zweiten Task und eine zweite Belastung erzeugen.

Client-Timeouts, geschlossene Browser-Tabs und abgebrochene Streams brechen einen angenommenen Task nicht ab, und ein angenommener Task lässt sich nicht abbrechen.

Der Task ist fehlgeschlagen

Bei fehlgeschlagenen oder abgelaufenen Tasks wird die Reservierung normalerweise vollständig freigegeben. Einige Inhaltsablehnungen werden zum angenommenen Angebotspreis berechnet, sofern die Modellseite diese Ausnahme ausdrücklich nennt. Prüfen Sie den endgültigen Betrag anhand von settled und cost.

• Nicht unverändert wiederholen: invalid_request, unsupported_combination, content_rejected (das gewählte Modell hat den Inhalt abgelehnt; ändern Sie den Prompt oder das Modell).
• Nach einer Pause lohnt ein neuer Versuch: rate_limited, upstream_unavailable, upstream_failed.
• Zuerst beheben: invalid_asset (laden Sie die Datei erneut hoch), timeout (versuchen Sie eine kürzere Dauer oder eine niedrigere Auflösung), generation_failed (mit denselben Eingaben scheitert es meist auf dieselbe Weise).

errorMessage erklärt den Grund für Menschen; es kann die eigene Begründung des Modells auf Englisch sein. Verzweigen Sie in Ihrem Code ausschließlich nach errorCode. Die vollständige Tabelle der Fehlercodes von Tasks steht unter Fehler. Eine Wiederholung ist ein neuer Task und wird bei Erfolg erneut berechnet.

Der Task bleibt in queued oder running

Generieren braucht Zeit; ein langes Video kann mehrere Minuten dauern. Jeder Task hat eine serverseitige Frist, die recordInfo als deadlineAt liefert:

• Vor deadlineAt: Warten Sie weiter auf den Callback, oder pollen Sie recordInfo mit wachsenden Pausen (nicht jede Sekunde).
• Nach der Frist: Der Task endet von selbst mit expired und errorCode: "timeout", und seine Reservierung wird vollständig zurückgegeben. Sie müssen nichts abbrechen, und angenommene Tasks lassen sich ohnehin nicht abbrechen.

Bleibt ein Task deutlich über sein deadlineAt hinaus in running, wenden Sie sich mit der Task-ID an den Support.

Upload erfolgreich, aber die Eingabe wird abgelehnt

• Sie haben die Bestätigung übersprungen. Ein erfolgreicher PUT der Datei reicht nicht: Rufen Sie files/{fileId}/commit auf und übergeben Sie dann die zurückgegebene spicy://-URI im Eingabefeld des Modells. Übergeben Sie niemals die uploadUrl selbst.
• Die Datei passt nicht zum Ticket. Prüfen Sie den angegebenen Content-Type, die Größe und das Format; eine Abweichung liefert 40003.
• Sie ist abgelaufen. Eine hochgeladene Datei lässt sich bis zum expiresAt aus der Commit-Antwort verwenden: standardmäßig 1 Tag, oder kürzer, wenn Ihr Konto Uploads nach Ende des Tasks löscht. Für die Wiederholung eines Tasks brauchen Sie deshalb unter Umständen einen neuen Upload.
• Sie gehört zu einem anderen Konto. Eine spicy://-URI funktioniert nur mit Schlüsseln des Kontos, das sie hochgeladen hat.

Den vollständigen Upload-Ablauf beschreibt Medien.

Callback fehlt oder Download abgelaufen

Es kam kein Callback an:

1. Prüfen Sie, ob callBackUrl eine https://-Adresse ist, die aus dem Internet erreichbar ist. Reines http:// wird nicht akzeptiert.
2. Prüfen Sie, ob Ihr Empfänger die Signatur über die ursprünglichen Bytes der Anfrage prüft, bevor er JSON parst, und schnell mit einem 2xx antwortet. Langwierige Arbeit gehört in Ihre eigene Warteschlange. Wurde der Signaturschlüssel kürzlich erneuert, muss der Empfänger den neuen verwenden: Es gibt keine Übergangszeit. Siehe Webhooks.
3. Sehen Sie sich den Zustellverlauf in der Konsole unter Webhooks an; dort können Sie eine Zustellung auch wiederholen.
4. Lesen Sie den Task in der Zwischenzeit mit recordInfo: Polling ist immer eine gültige Ausweichlösung. Siehe Webhooks.

Callbacks können mehrfach oder verspätet ankommen; entfernen Sie also Duplikate, bevor Sie eine Bestellung ausführen.

Der Download-Link oder die Datei ist weg:

• Ein Download-Link gilt 20 Minuten. Wird das Ergebnis noch aufbewahrt, fordern Sie einfach einen neuen Link an; einen alten Link aufzufrischen funktioniert nicht.
• Wird das Ergebnis gerade noch in den Speicher kopiert, warten Sie ein paar Sekunden und fragen Sie erneut.
• Ergebnisse werden höchstens etwa 14 Tage aufbewahrt, und kürzer, wenn Ihr Konto eine kürzere Aufbewahrung eingestellt hat. Steht contentState auf expired oder purged, lässt sich die Datei nicht wiederherstellen; führen Sie das Modell erneut aus. Siehe Datenaufbewahrung und Löschung.

Stream endet vorzeitig

Prüfen Sie den HTTP-Status und den Content-Type, bevor Sie den Stream für Ihr Protokoll parsen. Netzwerk-Chunks sind keine vollständigen Ereignisse, und eine geschlossene Verbindung ist kein Erfolgszeichen: Achten Sie auf das Abschlussereignis des Protokolls, auf Fehlerereignisse und auf Ihre eigene Frist in der Anwendung. Gehen Sie nicht davon aus, dass ein abgebrochener Stream kostenlos war oder sich ohne Kosten erneut senden lässt: Gültige Nutzung, die vor dem Abbruch erfasst wurde, kann berechnet werden. Bewahren Sie die request_id auf und prüfen Sie Ihre Verbrauchsdaten. Siehe Text und Streaming.

Berechtigungen im Team

• Sie können keinen Schlüssel anlegen. Die Bereichsauswahl oben in der linken Seitenleiste der Konsole steht auf einem Team, in dem Ihre Rolle Budgetverwalter oder Nur lesen ist. Zum Anlegen von Schlüsseln brauchen Sie die Rolle Inhaber, Admin oder Entwickler. Wechseln Sie zu Ihrem Bereich Persönlich, oder bitten Sie einen Team-Admin um die Rolle Entwickler.
• Sie sehen einen Task, aber nicht seinen Prompt oder sein Ergebnis. Budgetverwalter und Mitglieder mit Nur lesen sehen nur Status, Kosten und Verbrauch.
• Sie können eine Einladung nicht annehmen. Melden Sie sich mit genau der E-Mail-Adresse an, an die die Einladung ging. Einladungen laufen nach 7 Tagen ab; ist Ihre abgelaufen, bitten Sie um eine neue.
• Ein Teamschlüssel stoppt mit 40201. Teamschlüssel verbrauchen das Guthaben des Team-Inhabers, also muss der Inhaber Guthaben aufladen.

Rollen und Teamgrenzen erklärt Konsole und Teams.

Rechnung lässt sich nicht ausstellen

• Ihre Angaben sind unvollständig. Eine Rechnung braucht einen Namen (Ihre Firma oder Ihren eigenen), Adresszeile 1, Stadt und Land, einmalig eingetragen oben unter Abrechnung → Rechnungen.
• Ein Zeichen lässt sich nicht drucken. Auf einer Rechnung können nur lateinische, griechische und kyrillische Zeichen stehen. Schreiben Sie einen japanischen oder koreanischen Firmennamen in seiner eingetragenen lateinischen Umschrift.
• Sie existiert bereits. Für jede bezahlte Aufladung und jeden abgeschlossenen Monat lässt sich genau ein Dokument ausstellen; laden Sie das vorhandene herunter. Um Angaben zu korrigieren, wählen Sie dort Neu ausstellen.
• Der Monat ist nicht verfügbar. Eine Nutzungsaufstellung gibt es nur für Monate, die vorbei sind und in denen Sie etwas ausgegeben haben.

Siehe Abrechnung zu Rechnungen und Nutzungsaufstellungen.

Verwandte Abläufe

Fehler · Integration für den Produktivbetrieb · Idempotenz · Medien · Webhooks · Text und Streaming · Konto einrichten