Warum wird bei fehlgeschlagenen HiAPI-Anfragen trotzdem abgebucht?

Symptom

Du sendest einen Generierungsauftrag per POST an https://api.hiapi.ai/v1/tasks und fragst dann per GET /v1/tasks/:id ab. Das Ergebnis: "status": "fail" plus ein error-Objekt, zum Beispiel {"code": "TASK_FAILED", "message": "task failed"}. Der HTTP-Statuscode dieser Abfrage selbst ist ein normales 200 – HiAPI verpackt die Fehlerinformation im JSON-Body, nicht im Statuscode. Weil dieser Auftrag tatsächlich queued → handling durchlaufen hat, bevor er fehlschlug, liegt die Vermutung nahe, dass dieser Versuch wie ein normaler Aufruf abgerechnet wurde. Tatsächlich bedeutet der Endzustand fail nicht, dass Geld abgebucht wurde – aber wenn du dein Guthaben prüfst, bevor die Rückerstattung eingegangen ist, lässt die Reservierung zum Zeitpunkt der Erstellung den Kontostand so aussehen, als wäre Geld abgebucht worden.

Häufige Ursachen

1. Die „Reservierung“ wird für eine „Abbuchung“ gehalten. HiAPI reserviert die geschätzten Kosten eines Auftrags in dem Moment, in dem er erstellt wird und noch nicht wirklich läuft. Diese Reservierung schlägt sofort auf deinem Guthaben durch – aber sie ist noch keine Abbuchung.
2. Das Guthaben wird während der Laufzeit des Auftrags geprüft. Zwischen queued/handling und dem Endzustand bleibt diese Reservierung bewusst „offen“ – das ist so vorgesehen. Erst der Endzustand (success oder fail) gleicht sie aus.
3. „Downstream ist wirklich gelaufen, aber fehlgeschlagen“ wird mit „bereits bei der Erstellung abgelehnt“ verwechselt. Ein Auftrag, der status: "fail" erreicht (zum Beispiel error.code: "TASK_FAILED"), wurde wirklich erstellt, ist wirklich gelaufen und ist downstream fehlgeschlagen – die HiAPI-Dokumentation stellt ausdrücklich klar, dass der reservierte Betrag nach Erreichen dieses Endzustands automatisch vollständig zurückerstattet wird. Eine Anfrage hingegen, die nie eine taskId erhalten hat – etwa ein synchron zurückgegebenes 402 INSUFFICIENT_QUOTA – wurde abgelehnt, bevor der Auftrag existierte, und es wurde gar nichts reserviert. Von außen sehen beide wie ein „Fehlschlag“ aus, aber nur der erstere hat den Reservierungsmechanismus tatsächlich berührt.
4. Idempotency-Key falsch verwendet. Ein erneutes Senden mit demselben Key und demselben Request-Body liefert nur die ursprüngliche taskId zurück – es wird kein neuer Auftrag erstellt und nichts ein zweites Mal abgebucht. Wird derselbe Key jedoch mit einem geänderten Request-Body erneut gesendet, gibt es in der Erstellungsphase direkt 422 IDEMPOTENCY_KEY_MISMATCH; wird derselbe Key erneut gesendet, während der erste Aufruf noch nicht verarbeitet ist, gibt es 409 IDEMPOTENCY_KEY_PROCESSING. Über keinen dieser Wege entsteht ein abrechenbarer Auftrag.

Behebungsschritte

1. Frage GET /v1/tasks/:id ab und schaue direkt auf data.status – rate das Abrechnungsergebnis nicht anhand eines einzelnen Guthaben-Screenshots. queued, handling und archiving sind keine Endzustände; nur success und fail sind Endzustände.
2. Ist data.status gleich "fail", ist das ein Ergebnis, das zurückerstattet wird. Schau dir data.error.code an (zum Beispiel TASK_FAILED), um die Ursache zu verstehen, und prüfe dann erneut dein Guthaben – die Rückerstattung erfolgt automatisch, sobald der Auftrag diesen Endzustand erreicht.
3. Hat der Aufruf POST /v1/tasks selbst einen Nicht-2xx-Statuscode zurückgegeben (400/402/409/415/422) und enthält der Body keine taskId, gibt es nichts zu erstatten – denn es wurde weder ein Auftrag erstellt noch etwas abgebucht. Der konkrete Fall unzureichenden Guthabens zeigt sich als error_code: "INSUFFICIENT_QUOTA" in einer 402-Antwort.
4. Prüfe im HiAPI-Abrechnungsportal die Transaktionspaarung „Reservierung – Rückerstattung“, statt nur den Guthabenstand zu einem bestimmten Zeitpunkt zu betrachten.
5. Wenn du einen fehlgeschlagenen Auftrag erneut versuchst, gib diesem tatsächlich neuen Versuch einen neuen Idempotency-Key. Sende nicht mit dem alten Key und geändertem Request-Body erneut (das löst 422 aus), und sende nicht mit demselben Key erneut, während die erste Anfrage noch verarbeitet wird (das löst 409 aus).
6. Wenn du sicher bist, dass der Auftrag den Endzustand fail erreicht hat, der reservierte Betrag aber nach einiger Zeit immer noch nicht zurückerstattet wurde, liegt das außerhalb des Bereichs dieses automatischen Rückerstattungsmechanismus – wende dich direkt an den Support und gehe nicht davon aus, dass es sich von selbst wieder einrenkt.

Minimales Verifikationsbeispiel

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": { "prompt": "a minimalist desk setup, studio lighting" }
  }'

Hier trägt das model-Feld das Routing-Suffix /text-to-image. Zum Zeitpunkt der Erstellung dieses Artikels enthält der HiAPI-Modellindex für die Gruppe gpt-image-2 nur Einträge mit Routing-Suffix (/text-to-image, /image-to-image), keine Einträge mit bloßer id. Ob und welches Suffix erforderlich ist, richtet sich unbedingt nach den Einträgen mit availability: "online" in diesem live gepflegten Modellindex – übernimm nicht die Schreibweise anderer Modelle oder älterer Dokumentationen.

Nach Erhalt der zurückgegebenen taskId abfragen:

curl -s https://api.hiapi.ai/v1/tasks/$TASK_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

So sieht ein fehlgeschlagener, zurückerstatteter Auftrag aus:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "gpt-image-2/text-to-image",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": { "code": "TASK_FAILED", "message": "task failed" }
  }
}

Verwandte interne Links

• HiAPI-Abrechnungsportal
• HiAPI Unified Async Task API: Fehlercodes und Statusbeschreibungen
• HiAPI-Auftrag hängt oder läuft in ein Timeout: Diagnose- und Wiederholungsleitfaden
• HiAPI-Fehlerbehebung für „model not found“ / „model not available“

FAQ

Wird mir Geld abgebucht, wenn ein Bild- oder Videoauftrag bei HiAPI fehlschlägt? Nein. Sobald ein Auftrag den Endzustand fail erreicht, wird der bei der Erstellung reservierte Betrag automatisch vollständig zurückerstattet.

Mein Guthaben ist direkt nach dem Absenden des Auftrags gesunken, und der Auftrag ist später fehlgeschlagen – warum ist das Guthaben nicht zurückgekommen? Diese Verringerung ist die Reservierung bei der Erstellung, keine Abbuchung. Sie wird automatisch ausgeglichen, sobald der Auftrag den Endzustand erreicht – bei fail wird sie zurückerstattet, erst bei success wird sie tatsächlich verbraucht.

Worin unterscheidet sich ein 402-Fehler von einem fehlgeschlagenen Auftrag? 402 INSUFFICIENT_QUOTA bedeutet, dass der Auftrag gar nicht erst erstellt wurde – es gibt also nichts zu reservieren und nichts zu erstatten. Ein Auftrag hingegen, der eine taskId erhalten hat und dessen status später zu "fail" wird, wurde wirklich erstellt, ist wirklich gelaufen und ist dann downstream fehlgeschlagen; HiAPI erstattet diese Reservierung automatisch zurück.

Wird mir bei einem erneuten Versuch mit demselben Idempotency-Key zweimal Geld abgebucht? Nein. Ein erneutes Senden mit demselben Key und demselben Request-Body liefert nur die ursprüngliche taskId zurück und erstellt keinen neuen Auftrag. Wird unter demselben Key ein geänderter Request-Body gesendet, gibt es direkt 422 IDEMPOTENCY_KEY_MISMATCH, und es entsteht ebenfalls kein doppelter Auftrag.

Wo kann ich die Aufzeichnungen zu Reservierung und Rückerstattung einsehen? In den Abrechnungs- und Transaktionsaufzeichnungen des HiAPI-Abrechnungsportals.