Tutorial

HiAPI-Aufgaben-Timeout und 504-Fehler: Diagnose- und Behebungsleitfaden

Oct 8, 2026

Bei HiAPI-Aufgaben kann in der Antwort von GET /v1/tasks/{id} manchmal "status": "fail" und "error": {"code": "TASK_TIMEOUT", "message": "Task timed out"} auftauchen – beachten Sie, dass der HTTP-Statuscode dieser Antwort selbst 200 ist. Dies ist ein in der HiAPI-Dokumentation beschriebener echter Fehlerstatus: Er bedeutet, dass die Aufgabe bereits mit der Ausführung begonnen hat, aber nicht innerhalb des internen Zeitbudgets abgeschlossen werden konnte. Wenn Sie stattdessen kein solches JSON sehen, sondern der Client direkt einen nackten HTTP-504 Gateway Timeout wirft, dann stammt dieser keineswegs von der HiAPI-API: 504 steht in keiner der dokumentierten Statuscodelisten von HiAPI. Dieser Artikel behandelt beide Fälle getrennt: wie man ein echtes TASK_TIMEOUT liest und behebt; und woher ein 504 tatsächlich kommt.

Wie die Fehlermeldung tatsächlich aussieht

Der Aufgabenablauf bei HiAPI ist asynchron: POST /v1/tasks gibt sofort eine taskId zurück, danach fragen Sie per Polling mit GET /v1/tasks/{id} das Ergebnis ab. Erst wenn status einen Endzustand erreicht, erscheint das Feld error. Ein echtes Timeout sieht so aus:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-xxxxxxxx",
    "model": "gpt-image-2",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": { "code": "TASK_TIMEOUT", "message": "Task timed out" }
  }
}

Beachten Sie, dass der HTTP-Statuscode dieser Antwort 200 ist – die Polling-Anfrage selbst war erfolgreich, fehlgeschlagen ist die Aufgabe, und die Fehlerdetails stehen in data.error. Das unterscheidet sich von synchronen Fehlern in der Erstellungsphase (z. B. unzureichendes Guthaben ist 402, ein fehlerhafter Request-Body ist 400); solche Fehler werden sofort beim ursprünglichen POST /v1/tasks-Aufruf zurückgegeben, wenn die Aufgabe noch gar nicht erstellt wurde. TASK_TIMEOUT kann nur bei einer bereits erfolgreich erstellten Aufgabe auftreten.

Und 504 ist in den meisten Fällen überhaupt kein Response-Body, sondern ein Statuscode, den ein Proxy, Load Balancer oder eine HTTP-Client-Bibliothek selbst ausgibt, wenn sie das Warten auf jegliche Antwort aufgibt. Die in der HiAPI-Dokumentation beschriebenen HTTP-Statuscodes sind 200, 400, 402, 404, 409, 415, 422, 503 – darunter ist kein 504. Falls Sie tatsächlich 401 sehen, ist das ein anderes Problem (API Key ungültig oder deaktiviert, kein Timeout) und nicht Gegenstand dieses Artikels.

Häufige Ursachen (nach Trefferwahrscheinlichkeit sortiert)

Echtes Timeout auf Aufgabenebene. Das Modell hat die Aufgabe erhalten, konnte sie aber nicht innerhalb des internen Zeitbudgets abschließen. Genau das ist das oben gezeigte TASK_TIMEOUT-Szenario, das bei schwereren Aufgaben häufiger auftritt – längere Videodauer, höhere Auflösung oder ein kurzzeitig überlastetes Modell.
504 stammt von außerhalb von HiAPI. Die allermeisten „504"-Meldungen sind tatsächlich der Read Timeout des Clients selbst (die HTTP-Bibliothek wartet nicht länger und gibt auf), oder ein Firmenproxy, VPN oder Load Balancer zwischen Ihnen und api.hiapi.ai hat die Verbindung nach seinen eigenen Timeout-Einstellungen getrennt. Da HiAPI nie 504 zurückgibt, handelt es sich um ein Konfigurationsproblem auf Client- oder Netzwerkseite, nicht um eine Störung von HiAPI.
Aufgabe läuft noch und wird fälschlich als Timeout eingeschätzt. queued, handling, archiving sind alle keine Endzustände; in diesem Moment existiert das Feld error gar nicht. Wenn der Status bei einer Polling-Abfrage nicht success ist, bedeutet das nicht automatisch ein Timeout.

Behebungsschritte

Rufen Sie die Aufgabe per taskId ab und lesen Sie direkt status und error.code. Raten Sie die Ursache nicht aus einer allgemeinen Ausnahmemeldung in Ihrem Client-Code – rufen Sie GET /v1/tasks/{id} auf und sehen Sie sich den Response-Body selbst an.
Wenn status gleich "fail" und error.code gleich "TASK_TIMEOUT" ist: erneut versuchen. Die dokumentierte Behebung ist genau so einfach – reichen Sie die Aufgabe mit einem neuen POST /v1/tasks-Aufruf erneut ein (Sie erhalten eine neue taskId); weder Konto noch Key müssen gewechselt werden.
Wenn die Aufgabe selbst aufwendig ist, prüfen Sie zuerst die Eingabe. Längere Videodauer, höhere Auflösung oder sehr umfangreiche/komplexe Prompts bringen das Modell näher an seine Zeitbudget-Obergrenze. Wenn dieselbe Konfiguration wiederholt Timeouts erleidet, versuchen Sie eine niedrigere Auflösung/Dauer oder ein anderes Modell.
Wenn Sie tatsächlich einen nackten 504 sehen (kein JSON-Response-Body mit error.code), liegt das Problem außerhalb von HiAPI. Prüfen Sie den in Ihrem HTTP-Client oder SDK konfigurierten Read Timeout – viele Standardwerte sind zu kurz (10–30 Sekunden), und in einem asynchronen Ablauf sollte eine lange Anfrage ohnehin nicht blockieren, sondern separat gepollt werden. Stellen Sie außerdem sicher, dass Sie nicht über einen Firmenproxy, VPN-Gateway oder Load Balancer gehen, die Verbindungen nach ihren eigenen Timeout-Einstellungen unabhängig von HiAPI trennen können.
Wenn status noch queued, handling oder archiving ist, versuchen Sie noch nicht erneut. Es ist nichts wirklich fehlgeschlagen. Eine vollständigere Diagnose finden Sie im hiapi-Leitfaden zur Diagnose von hängenden/Timeout-Aufgaben (englisch).

Minimales Verifikationsbeispiel

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "input": {
      "prompt": "a single red apple on a white background, studio lighting"
    }
  }'

Dies gibt sofort eine taskId zurück:

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

Dann pollen Sie sie:

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

Eine normale Aufgabe gibt schließlich "status": "success" und das Ausgabeergebnis zurück. Eine tatsächlich abgelaufene Aufgabe gibt die oben gezeigte TASK_TIMEOUT-Struktur zurück. Wenn Sie einen 504 auf Verbindungsebene erhalten, ganz ohne JSON-Response-Body, dann bedeutet das, dass die Antwort überhaupt nicht von der HiAPI-API zurückübertragen werden konnte – prüfen Sie gemäß den obigen Schritten Ihre Client-Timeout-Einstellungen und den Netzwerkpfad, statt Ihr Konto zu verdächtigen.

FAQ

Sind das TASK_TIMEOUT von HiAPI und der HTTP 504 Gateway Timeout dasselbe? Nein. TASK_TIMEOUT ist ein dokumentierter HiAPI-Fehlercode, der in einer normalen 200-Antwort erscheint und bedeutet, dass der status der Aufgabe selbst zu fail geworden ist, weil die Aufgabe intern in ein Timeout gelaufen ist. 504 ist ein allgemeiner HTTP-Statuscode, den manche Proxys, Load Balancer oder HTTP-Client-Bibliotheken ausgeben, wenn sie das Warten auf eine Antwort aufgeben; die HiAPI-API dokumentiert oder liefert 504 überhaupt nicht, daher stammt das wörtliche 504, das Sie sehen, zwangsläufig von einer Stelle zwischen Ihnen und HiAPI oder von Ihrem eigenen Client, der das Warten aufgegeben hat – nicht von einer Störung des HiAPI-Servers.

Was sollte ich bei einem TASK_TIMEOUT tun? Reichen Sie einfach eine neue Aufgabe ein. Die dokumentierte Behebung für TASK_TIMEOUT ist schlicht ein erneuter Versuch; es gibt keinen separaten Entsperrschritt, und sofern nicht dieselbe Eingabe wiederholt Timeouts erleidet, müssen weder Prompt noch Parameter geändert werden.

Wird bei einem erneuten Versuch einer abgelaufenen Aufgabe doppelt abgerechnet? Die dokumentierte Fehlercodetabelle von HiAPI sagt dazu nichts Explizites aus. Wenn Ihnen das wichtig ist, prüfen Sie die Nutzungsaufzeichnungen in der Konsole mit dieser konkreten taskId, statt Annahmen zu treffen.

Mein HTTP-Client hat eine Timeout-Ausnahme geworfen, kein JSON-förmiges TASK_TIMEOUT – ist das dasselbe? Nein. Ein clientseitiges Timeout (z. B. ReadTimeout einer HTTP-Bibliothek oder ein 504 von einem Firmenproxy) bedeutet, dass Ihre Verbindung aufgegeben hat, bevor überhaupt eine HiAPI-Antwort eintraf; das heißt nicht, dass die Aufgabe selbst fehlgeschlagen ist. Da /v1/tasks asynchron ist, besteht die übliche Behebung darin, den Read Timeout des Clients zu erhöhen (oder gar nicht blockierend auf dem initialen POST zu warten) und separat GET /v1/tasks/{id} zu pollen, bis ein Endzustand erreicht ist.

Die Aufgabe ist seit mehreren Minuten queued oder handling, ohne Fehler – zählt das als Timeout? Noch nicht. queued, handling, archiving sind alle keine Endzustände; das Feld error erscheint erst, wenn status zu fail wird. Wenn die Aufgabe wirklich nicht zu einem Abschluss kommt, finden Sie im hiapi-Leitfaden zur Diagnose von hängenden/Timeout-Aufgaben (englisch) eine vollständige Aufschlüsselung laufender Ursachen wie Stau in der Warteschlange.