HiAPI 502 / 503-Upstream-Fehler: Ursachen und Behebung

Sie rufen POST https://api.hiapi.ai/v1/tasks auf (oder fragen GET /v1/tasks/{id} ab), und statt der üblichen 200 mit einer taskId erhalten Sie 502 Bad Gateway oder 503 Service Unavailable. Beide sind 5xx-Antworten, was bedeutet, dass das Problem auf der Server- oder Übertragungsseite liegt und nicht bei Ihrer Anfrage: Sie haben keine falschen Parameter, keinen falschen Schlüssel und keine fehlerhaft formatierte Nutzlast gesendet. 503 ist das in der HiAPI-Dokumentation dokumentierte Signal „Plattform vorübergehend nicht verfügbar“, das Ihnen sagt, dass Sie es erneut versuchen sollten; 502 ist eine Gateway-Antwort, die irgendwo auf der Strecke entsteht. Dieser Leitfaden erklärt, wie Sie dies bestätigen, wie Sie sicher erneut versuchen, ohne doppelte Arbeit zu leisten, und wie Sie 502/503 von 504-Timeouts und TASK_FAILED-Ergebnissen unterscheiden.

Wie sich 502 oder 503 tatsächlich äußert

In der HTTP-Statuszeile sehen Sie eines der folgenden Elemente anstelle des normalen 200:

• 503 Service Unavailable – dieses ist dokumentiert. Die Dokumentation der asynchronen API von HiAPI führt 503 als „Plattform vorübergehend nicht verfügbar; bitte später mit exponentiellem Backoff erneut versuchen“, mit dem entsprechenden Business-Code TEMPORARILY_UNAVAILABLE („Der Generierungsdienst ist vorübergehend nicht verfügbar. Bitte später erneut versuchen; wenn das Problem weiterhin besteht, wenden Sie sich an den Support.“). Die synchronen Fehler von HiAPI verwenden einen flachen JSON-Umschlag – in der Dokumentation für 400 sieht das so aus: {"code": 400, "message": "...", "data": null, "error_code": "INVALID_REQUEST"} – daher sollte ein von der API zurückgegebener 503 denselben Umschlag mit error_code: "TEMPORARILY_UNAVAILABLE" verwenden.
• 502 Bad Gateway – dieses ist nicht in den dokumentierten Statuscodes von HiAPI enthalten. In Standard-HTTP bedeutet 502, dass ein Gateway oder Proxy eine ungültige oder leere Antwort von der nächsten Stelle erhalten hat, die er aufzurufen versuchte. Ein von Ihnen empfangener 502 wurde daher von einem Gateway auf der Strecke erzeugt – möglicherweise die Edge-/CDN-Schicht, ein Load Balancer oder ein Proxy in Ihrem eigenen Netzwerk – und nicht von der HiAPI-Anwendung, die ihren üblichen JSON-Umschlag zurückgibt. Der Antworttext ist normalerweise eine kurze HTML- oder Klartext-Gateway-Seite, und dieser Nicht-JSON-Textkörper ist selbst ein Signal: Er zeigt an, dass es sich um eine Übertragungs-/Gateway-Situation handelt und nicht um einen Anwendungsfehler mit festem, dokumentiertem Payload.

In beiden Fällen ist der Status 5xx: Das Problem liegt auf der Server- oder Übertragungsseite, nicht bei Ihrer Anfrage. Das ist das Gegenteil von 4xx – 400 (Parameterfehler), 401 (falscher Schlüssel; HiAPI gibt ein verschachteltes {"error": {"code": "permission_denied", "type": "hiapi_error", "request_id": "..."}} zurück) oder 402 (unzureichendes Guthaben) – die alle erfordern, dass Sie etwas auf Ihrer Seite ändern, um sie zu beheben. 502/503 lassen sich nicht durch Ändern der Nutzlast beheben.

Häufige Ursachen (von der wahrscheinlichsten zur unwahrscheinlichsten)

1. Kurzzeitige Plattformüberlastung oder Wartungsfenster → 503 TEMPORARILY_UNAVAILABLE. Dies ist der erwartete, dokumentierte Fall. Er behebt sich von selbst, und ein erneuter Versuch mit Backoff wird erfolgreich sein.
2. Kurzzeitige Störung eines Gateways oder Proxys auf der Strecke → 502. Die Edge-/CDN-Schicht, ein Load Balancer oder ein Proxy in Ihrem eigenen Netzwerk konnte die Antwort kurzzeitig nicht weiterleiten. Ebenfalls vorübergehend.
3. Ein Verkehrsspitze hat eine Begrenzung ausgelöst. Unter hoher Last sehen Sie möglicherweise stattdessen 429 RATE_LIMITED („Bitte später erneut versuchen; vermeiden Sie es, dieselbe Anfrage sofort erneut zu senden“). Wenn der Status 429 ist, besteht die Lösung darin, die Sendegeschwindigkeit zu reduzieren, nicht darin, heftiger erneut zu versuchen.
4. Das angeforderte Modell-Backend ist vorübergehend nicht verfügbar. HiAPI protokolliert dies auf Aufgabenebene als MODEL_UNAVAILABLE („Bitte später erneut versuchen oder das Modell wechseln“); eine kurze plattformweite Störung, die dieses Modell bedient, kann sich ebenfalls als 503 äußern.
5. Nicht ein Schlüsselfehler, ein fehlerhafter Anforderungstext oder unzureichendes Guthaben. Diese sind 401 / 400 / 402 und äußern sich nie als 502 oder 503.

Behebung Schritt für Schritt

1. Bestätigen Sie, dass es sich um einen 5xx und nicht um einen 4xx handelt. Prüfen Sie zuerst den Statuscode. 502/503 gehören zur Server-/Übertragungsseite; 400, 401, 402, 404, 409, 415, 422 und 429 gehören zu Ihrer Seite. Wenn es tatsächlich 502/503 ist, beginnen Sie nicht damit, den Anforderungstext neu zu schreiben – das hilft nur bei 4xx.
2. Versuchen Sie es mit exponentiellem Backoff mit Jitter erneut. Die Dokumentation verlangt ausdrücklich exponentielles Backoff für 503. Ein sicheres Client-Muster ist, mit etwa 1 Sekunde zu beginnen und sich bei jedem Versuch zu verdoppeln (2 s, 4 s, 8 s …), mit einer Obergrenze von etwa 30–60 Sekunden und zufälligem Jitter, damit nicht viele Clients synchron erneut versuchen. Diese Intervalle sind empfohlene Client-Muster, keine von HiAPI veröffentlichten Zeitgarantien.
3. Machen Sie die Übermittlung idempotent. Setzen Sie den Header Idempotency-Key auf POST /v1/tasks (eine beliebige UTF-8-Zeichenkette, maximal 255 Byte). Wenn Sie aufgrund eines 502/503 unsicher sind, ob die Aufgabe tatsächlich erstellt wurde, ist ein erneuter Versuch mit dem gleichen Schlüssel sicher: Gleicher Schlüssel + gleicher Anforderungstext geben die ursprüngliche taskId mit dem Antwortheader Idempotent-Replay: true zurück, anstatt eine zweite Aufgabe zu erstellen oder eine zweite Abbuchung zu verursachen. Schlüssel sind kontobezogen und laufen nach 24 Stunden ab. Die vollständige Vereinbarung finden Sie in der Dokumentation der Unified Async API.
4. Machen Sie nicht blind ein erneutes POST ohne Schlüssel. Wenn Sie ohne Idempotency-Key übermittelt haben und einen 502/503 erhalten haben, haben Sie möglicherweise bereits eine Aufgabe erstellt, die Sie nicht sehen – Sie haben keine taskId, die Sie abfragen können, sodass ein naiver erneuter Versuch das Risiko doppelter Arbeit und doppelter Abbuchung birgt. Fügen Sie den Schlüssel hinzu, bevor Sie in irgendeinem Umfang erneut versuchen.
5. Wenn 502/503 während der Abfrage auftritt, fragen Sie einfach weiter ab. Ein 5xx von GET /v1/tasks/{id} ändert den Aufgabenstatus nicht. Endzustände (success / fail) sind nach Erreichen fest und gehen nie ineinander über, daher reicht es, nach einem Backoff erneut abzufragen. Alternativ können Sie callback.url registrieren, sodass Sie im Endzustand benachrichtigt werden, anstatt durch vorübergehende 5xx hindurch abzufragen – die Zustellung erfolgt mindestens einmal, daher sollten Sie nach taskId deduplizieren.
6. Unterscheiden Sie dies von Fehlern auf Aufgabenebene. Wenn Sie stattdessen HTTP 200 mit "status": "fail" erhalten, ist das kein 502/503 – die Aufgabe wurde akzeptiert, ausgeführt und ist fehlgeschlagen. Behandeln Sie TASK_FAILED („einmal erneut versuchen; wenn das Problem weiterhin besteht, wenden Sie sich an den Support“) oder TASK_TIMEOUT („die Aufgabe erneut versuchen“) jeweils entsprechend, anstatt blind Gateway-Wiederholungen durchzuführen.
7. Wenn es weiterhin besteht, eskalieren statt draufhämmern. Wenn 502/503 nach mehreren Backoff-Wiederholungen über mehrere Minuten weiterhin auftritt, behandeln Sie es als vorübergehendes Plattformereignis und nicht als etwas, das mit roher Gewalt gelöst werden kann. Hören Sie mit aggressiven Wiederholungen auf und wenden Sie sich an den Support, wobei Sie die request_id angeben, falls der Fehlertext sie enthält. Sie können im HiAPI-Konsolenbereich prüfen, ob Ihr Konto und Ihre Konnektivität in Ordnung sind.

Vergleich von 502 / 503 mit 504 und TASK_FAILED

Diese sind leicht zu verwechseln, da sie alle „nicht sauber zurückgegeben“ bedeuten, aber unterschiedliche Behandlung erfordern:

Antwort	HTTP-Statuscode	Quelle	Wird die Aufgabe abgebucht?	Was zu tun ist
503 Service Unavailable	503 (dokumentiert)	HiAPI-Plattform – vorübergehend nicht verfügbar oder überlastet	Aus der Antwort nicht ersichtlich; die Aufgabe kann bereits existieren	Mit Backoff und demselben Idempotency-Key erneut versuchen
502 Bad Gateway	502 (nicht in der HiAPI-Dokumentation)	Gateway/Proxy auf der Strecke (Edge, Load Balancer oder Ihr eigener Proxy)	Aus der Antwort nicht ersichtlich	Idempotenter erneuter Versuch mit Backoff; wenn es nur von Ihrem Netzwerk aus auftritt, prüfen Sie einen Proxy auf Ihrer Seite
504 Gateway Timeout	504 (nicht in der HiAPI-Dokumentation)	Ein Gateway oder Proxy auf der Strecke, der das Warten eingestellt hat (in der HiAPI-Dokumentation ist 504 nicht aufgeführt)	Aus der Antwort nicht ersichtlich	Wie bei 502; HiAPI meldet seine eigenen Timeouts als TASK_TIMEOUT
TASK_TIMEOUT	200 + "status": "fail"	HiAPI – Aufgabe wurde ausgeführt, überschritt aber das Zeitbudget	Nein (reservierter Betrag wurde zurückerstattet)	Die Aufgabe als neue Anfrage erneut versuchen
TASK_FAILED	200 + "status": "fail"	HiAPI – Aufgabe wurde akzeptiert und ausgeführt und ist dann fehlgeschlagen	Nein (reservierter Betrag wurde zurückerstattet)	Einmal erneut versuchen, dann error.message lesen
429 RATE_LIMITED	429	HiAPI – Sie senden zu schnell	Keine Aufgabe	Backoff; nicht sofort erneut senden
400 / 401 / 402	4xx	HiAPI – clientseitig (Fehler bei Anforderungstext/Schlüssel/Guthaben)	Nein	Anfrage, Schlüssel oder Guthaben korrigieren; erneute Versuche helfen nicht

Ein Satz zur Unterscheidung: 502/503/504 sind HTTP-Übertragungsfehler, die kein Aufgabenergebnis enthalten; TASK_FAILED / TASK_TIMEOUT kommen als HTTP 200 mit "status": "fail" und einem error-Objekt an. Ersteres bedeutet „Sie wissen nicht, ob die Anfrage angekommen ist“; Letzteres bedeutet „die Anfrage ist angekommen, die Aufgabe wurde ausgeführt und ist fehlgeschlagen“.

Minimales Verifizierungsbeispiel

Beweisen Sie mit einer sauberen Übermittlung, dass Ihr Schlüssel und Ihre Konnektivität in Ordnung sind, und grenzen Sie 502/503 als vorübergehendes Problem ein. Verwenden Sie eine Modell-ID, von der Sie sicher wissen, dass sie funktioniert (z. B. gpt-image-2/text-to-image), und fügen Sie Idempotency-Key hinzu, damit erneute Versuche sicher sind:

# A healthy submit returns 200 with a taskId. If this works but a specific
# call just 502/503'd, that 502/503 was transient — not your setup.
curl -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-job-0001" \
  -d '{"model":"gpt-image-2/text-to-image","input":{"prompt":"a red bicycle on a white background"}}'

# Then poll the task you just created (swap in the returned id):
curl -sS https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Wenn die Übermittlung selbst 200 und eine taskId zurückgibt, funktionieren Ihre Authentifizierung und Ihr Netzwerkpfad, und der vorherige 502/503 war ein vorübergehender Server-/Übertragungszustand – wiederholen Sie den fehlgeschlagenen Aufruf (wenn Sie denselben Idempotency-Key wiederverwenden, wird die ursprüngliche Aufgabe zurückgegeben und keine doppelte Aufgabe erstellt). Wenn die Übermittlung stattdessen 401 oder 400 zurückgibt, handelt es sich um ein clientseitiges Problem, nicht um 502/503.

Verwandte Lektüre

• HiAPI-Aufgaben-Timeout und 504-Fehler: So beheben Sie es – warum ein roher 504 nicht von HiAPI stammt und was TASK_TIMEOUT bedeutet.
• HiAPI TASK_FAILED-Fehler: Ursachen und Behebung – Behandlung von Aufgaben, die 200 + "status": "fail" zurückgeben.
• Wenn hiapi /v1/tasks-Jobs hängen bleiben oder ein Timeout auftritt: Diagnose und erneuter Versuch – ausführliche Einführung in Abfrageintervalle und Wiederholungsstrategien.
• So beheben Sie HiAPI-Ratenbegrenzungsfehler (429) – wenn das eigentliche Problem die Sendegeschwindigkeit und nicht die Verfügbarkeit ist.
• Warum werden fehlgeschlagene HiAPI-Anfragen trotzdem abgebucht? – wie Reservierung und Rückerstattung bei fehlgeschlagenen Aufgaben funktionieren.

Häufig gestellte Fragen

Sind 502 oder 503 mein Fehler? Nein. Beide sind 5xx-Antworten und gehören zur Server- oder Übertragungsseite. Ihr API-Schlüssel und Ihr Anforderungstext sind nicht die Auslöser – 4xx (400/401/402) ist die Kategorie, die Sie verursachen und beheben können. Die richtige Reaktion auf 502/503 ist ein idempotenter erneuter Versuch, nicht eine Codeänderung.

Was ist der Unterschied zwischen 502 und 503 bei HiAPI? 503 ist der in der HiAPI-Dokumentation dokumentierte Code „Plattform vorübergehend nicht verfügbar“ (error_code: TEMPORARILY_UNAVAILABLE) und stammt von der Plattform selbst. 502 ist nicht in den dokumentierten Statuscodes von HiAPI enthalten; in Standard-HTTP wird er von einem Gateway oder Proxy auf der Strecke ausgesendet, wenn das Upstream eine ungültige Antwort zurückgibt. Beide sind vorübergehend und erfordern einen erneuten Versuch mit Backoff, aber 502 kann auch auf einen Proxy in Ihrem eigenen Netzwerk hinweisen.

Wie unterscheidet sich 503 von 504? 503 bedeutet, dass der Dienst derzeit vorübergehend nicht verfügbar oder überlastet ist. 504 Gateway Timeout bedeutet, dass irgendwo zu lange auf eine Antwort gewartet wurde. In der HiAPI-Dokumentation ist 504 nicht aufgeführt; wenn Sie ihn sehen, hat ein Gateway oder Proxy auf der Strecke das Warten aufgegeben. Der eigene Status von HiAPI für „dauert zu lange“ ist das Aufgabenergebnis TASK_TIMEOUT (HTTP 200 + "status": "fail"). Siehe den 504-Leitfaden oben.

Wie unterscheide ich 502/503 von einem TASK_FAILED-Ergebnis? Schauen Sie auf den HTTP-Statuscode. 502/503 sind HTTP-Fehler ohne Aufgaben-Payload. TASK_FAILED kommt als HTTP 200 mit "status": "fail" und einem error-Objekt zurück – die Aufgabe wurde akzeptiert und ausgeführt. Verwenden Sie Backoff-Wiederholungen für 502/503; versuchen Sie bei TASK_FAILED einmal erneut und lesen Sie dann error.message.

Werde ich doppelt belastet oder wird eine doppelte Aufgabe erstellt, wenn ich nach einem 502/503 erneut versuche? Wenn Sie den Header Idempotency-Key auf POST /v1/tasks senden, nicht. Die Wiederverwendung desselben Schlüssels + Anforderungstexts gibt die ursprüngliche taskId zurück (Idempotent-Replay: true), anstatt eine doppelte Aufgabe zu erstellen. Außerdem werden fehlgeschlagene Aufgaben nie abgebucht – sobald eine Aufgabe den Endzustand „fehlgeschlagen“ erreicht, wird der bei der Erstellung reservierte Betrag vollständig zurückerstattet.

Wie lange sollte ich Backoff verwenden, und wann sollte ich eskalieren? Verwenden Sie exponentielles Backoff mit Jitter (z. B. 1 s, 2 s, 4 s, 8 s, mit Obergrenze und Zufälligkeit). Wenn 502/503 nach mehreren Wiederholungen über mehrere Minuten weiterhin zurückgegeben wird, hören Sie mit aggressiven Wiederholungen auf und wenden Sie sich unter Angabe der request_id aus dem Fehlertext an den Support – anhaltende 5xx deuten in der Regel auf ein vorübergehendes Plattformereignis hin und nicht auf etwas, das eine schnellere Wiederholungsschleife lösen kann.

Sollte ich die Anfrage-Nutzlast ändern, wenn ich 502/503 sehe? Nein. 502/503 ist kein Validierungsfehler, daher hilft das Ändern von Parametern nicht und kann die eigentliche vorübergehende Ursache verschleiern. Lassen Sie die Anfrage unverändert, fügen Sie Idempotency-Key hinzu, falls noch nicht geschehen, und versuchen Sie es dann mit Backoff erneut.