HiAPI gibt 402 – unzureichendes Guthaben (INSUFFICIENT_QUOTA) zurück – was tun? Ursachen und Lösungsschritte

Beim Aufruf der HiAPI-Schnittstelle kann gelegentlich eine HTTP-402-Antwort zurückkommen, und im Antwortkörper ist error_code gleich INSUFFICIENT_QUOTA. Das bedeutet, dass das Credits-Guthaben des Kontos aufgebraucht ist – es hat nichts damit zu tun, ob der API Key gültig ist, ob das Anfrageformat korrekt ist oder ob ein Rate Limit ausgelöst wurde. Die Aufgabe wird bereits vor der Erstellung abgelehnt, daher entstehen keinerlei Kosten. Die Lösung ist fast immer dieselbe: auf der Aufladungsseite Credits zum Konto hinzufügen und dann die gerade fehlgeschlagene Anfrage unverändert erneut senden.

Häufige Ursachen

1. Das Guthaben war schon 0. Neue Konten erhalten bei der Registrierung Gratis-Credits; sobald diese und spätere Aufladungen aufgebraucht sind, gibt jeder Aufruf zum Erstellen einer Aufgabe 402 zurück, bis das Guthaben wieder positiv ist.
2. Dichte Aufrufe in kurzer Zeit – das Guthaben wird schneller verbraucht als erwartet. Video-Modelle werden meist nach Ausgabesekunden abgerechnet; mehrere hintereinander laufende Videosequenzen verbrauchen oft deutlich mehr Credits als die gleiche Anzahl an Bildaufgaben, sodass das Guthaben schnell unbemerkt zur Neige geht.
3. 401 oder 429 mit 402 verwechselt. Prüfen Sie direkt den HTTP-Statuscode und das Feld error_code: 401 (error_code ähnlich wie permission_denied, der Key selbst ist ungültig oder deaktiviert) und 429 (error_code: RATE_LIMITED, Anfragen zu schnell) sehen beide wie ein „Aufruffehler“ aus, aber die Lösung unterscheidet sich völlig von 402 – im Log vermischt lässt sich leicht in die falsche Richtung suchen.

Lösungsschritte

1. Zuerst das Guthaben prüfen. Öffnen Sie im Konsolen-Dashboard die Abrechnungsseite und sehen Sie sich das aktuelle Credits-Guthaben an – dieser Schritt bestätigt direkt, ob der 402 tatsächlich am Guthaben liegt.
2. Das Konto aufladen. Fügen Sie ebenfalls auf der Abrechnungsseite Credits hinzu; es gibt keinen zusätzlichen „Freischalt“-Schritt, sobald das Guthaben positiv ist, gelingt das Erstellen von Aufgaben sofort.
3. Die vorherige Anfrage unverändert erneut senden. Es müssen keine Code- oder Parameteränderungen vorgenommen werden. Derselbe prompt, model und die übrigen Felder sind bei ausreichendem Guthaben sofort erfolgreich; wenn Sie unsicher sind, wie viel ein einzelner Aufruf eines Modells ungefähr kostet, sehen Sie zuerst auf der Preisseite nach.
4. Guthabenwarnung einrichten, um beim nächsten Mal nicht wieder darauf zu stoßen. In den Konsoleneinstellungen gibt es die Funktion „Balance Alerts“ (Guthabenwarnungen); fällt das Guthaben unter den von Ihnen festgelegten Schwellenwert, erhalten Sie eine E-Mail-Benachrichtigung, sodass Sie aufladen können, bevor es wirklich aufgebraucht ist.

Minimales Verifizierungsbeispiel

Mit der folgenden minimalen Anfrage lässt sich unabhängig bestätigen, dass das Problem am Kontoguthaben liegt, und Störungen durch das Modell oder das SDK selbst ausschließen:

curl https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a simple test image of a red circle on a white background"
  }'

Bei leerem Guthaben wird folgende Struktur zurückgegeben:

{
  "code": 402,
  "data": null,
  "error_code": "INSUFFICIENT_QUOTA",
  "message": "insufficient account balance; top up and retry"
}

Nach dem Aufladen und erneutem Senden derselben Anfrage erhalten Sie eine normale Antwort zur Aufgabenerstellung:

{
  "code": 200,
  "data": { "taskId": "tk-hiapi-xxxxxxxx" },
  "message": "success"
}

Beachten Sie, dass das Feld code mit dem HTTP-Statuscode übereinstimmt, error_code ein stabiler Wert für Verzweigungsentscheidungen ist und data bei fehlgeschlagener Erstellung stets null ist.

Verwandte interne Links

• HiAPI-Preise
• Abrechnung und Guthabenverwaltung
• Asynchrone Aufgabe erstellen (API-Dokumentation)

FAQ

Warum ist das Guthaben plötzlich aufgebraucht, vorher gab es keinen Hinweis? Standardmäßig bemerkt man das unzureichende Guthaben erst, wenn eine Aufgabe tatsächlich mit 402 fehlschlägt. Aktivieren Sie in den Konsoleneinstellungen die Guthabenwarnung (Balance Alerts); fällt das Guthaben unter den von Ihnen festgelegten Schwellenwert, erhalten Sie eine E-Mail und können rechtzeitig aufladen.

Unterbricht 402 eine bereits laufende Aufgabe? Nein. INSUFFICIENT_QUOTA wird in der Phase der Aufgabenerstellung zurückgegeben; zu diesem Zeitpunkt existiert die Aufgabe noch nicht, sodass von einer Unterbrechung einer laufenden Aufgabe keine Rede sein kann – es blockiert nur die Erstellung neuer Aufgaben.

Werden für Anfragen, die wegen 402 fehlschlagen, Kosten berechnet? Nein. Die Guthabenprüfung erfolgt, bevor die Aufgabe tatsächlich erstellt wird; 402 bedeutet, dass die Aufgabe nicht erstellt wurde und dem Konto keine Credits abgezogen wurden.

Sind 402 und Rate Limiting (429) dasselbe? Nein. Rate Limiting gibt 429 zurück, error_code ist RATE_LIMITED, was bedeutet, dass die Anfragen zu schnell gesendet werden; 402 bedeutet, dass das Credits-Guthaben des Kontos unzureichend ist, unabhängig von der Anfragerate – die Lösungen unterscheiden sich ebenfalls.

Wie erfahre ich rechtzeitig, bevor das Guthaben aufgebraucht ist? Öffnen Sie im Konsolen-Dashboard die Abrechnungsseite; dort sehen Sie das aktuelle Credits-Guthaben und die vollständige Verbrauchshistorie und können auch den Schwellenwert für Guthabenwarnungen festlegen.