API-Fehlercodes

Jeder Fehler, den dieses Gateway zurückgibt — am 2026-09-01 einzeln gegen den echten Endpunkt gemessen. Von den 7 Fehlern, die es zurückgibt, bedeuten 5 nicht das, was ihr Statuscode nahelegt, und 2 davon wiederholen die offiziellen SDKs, bevor dein Programm sie überhaupt zu sehen bekommt.

Geprüft am 2026-09-01

Statuscode führt in die Irre

Lies error.code, nicht den Statuscode

Ein falscher Modellname kommt als 503 zurück. Ein fehlendes messages-Feld als 500. Beides sind dauerhafte Fehler in deiner Anfrage — kein Wiederholungsversuch behebt sie —, aber openai-python, openai-node und die Anthropic-SDKs wiederholen 408, 409, 429 und alle 5xx standardmäßig zweimal, mit exponentiellem Backoff. So wird aus einem Tippfehler drei Runden und mehrere Dutzend Sekunden Wartezeit, bevor der eigentliche Grund erscheint. Dieser Grund stand von Anfang an im error.code des Bodys; gelogen hat der Statuscode.

Referenz

Statuscodes

Sortiert danach, wie häufig sie tatsächlich auftreten — nicht nach Zahlenwert.

  • HTTP 401leerer String
    Was wirklich passiert ist
    Der Key existiert nicht, wurde widerrufen, oder der Authorization-Header fehlt ganz.
    Was zu tun ist
    Prüfe auf der Seite „API-Keys“ in der Konsole, ob der Key noch da ist, oder erstelle einen neuen. Eines kannst du ausschließen: Es ist nicht das fehlende „Bearer “-Präfix — das Gateway nimmt den Key auch ohne, das ist also nie die Ursache.
    SDK wiederholt
    Nein — schlägt sofort fehl
    Am echten Endpunkt gemessen
    probes-errors.mjs: invalid-token / missing-auth
    Zurückgegebene Meldung
    Invalid token
  • HTTP 503model_not_foundStatuscode führt in die Irre
    Was wirklich passiert ist
    Diese Modell-ID steht nicht in diesem Katalog — meist aus der Dokumentation eines anderen Anbieters übernommen (gpt-4o, claude-sonnet-4-5). Es ist keine Störung: Für ein Modell, das hier nicht existiert, gibt es einfach keine Route.
    Was zu tun ist
    Vergleiche mit GET /v1/models, das ist die verbindliche Liste. Jede ID hier hat die Form anbieter/modell, zum Beispiel deepseek/deepseek-v4-flash.
    SDK wiederholt
    Ja — standardmäßig zweimal
    Am echten Endpunkt gemessen
    probes-errors.mjs: unknown-model
    Zurückgegebene Meldung
    No available channel for model gpt-4o under group y-api (distributor)
  • HTTP 403insufficient_user_quotaStatuscode führt in die Irre
    Was wirklich passiert ist
    Das Guthaben des Kontos ist auf null. Die Meldung ist auf Chinesisch und nennt das Restguthaben mit einem ＄ in voller Breite — deshalb findet eine Suche auf Englisch nichts.
    Was zu tun ist
    Lade unter https://y-api.bestvirtualgoods.com/app/billing auf. Das Guthaben ist sofort wieder da, bestehende Keys funktionieren weiter, und am Code ändert sich nichts.
    SDK wiederholt
    Nein — schlägt sofort fehl
    Im Upstream-Quellcode bestätigt, hier nicht ausgelöst
    service/billing_session.go:355-359
    Zurückgegebene Meldung
    用户额度不足, 剩余额度: ＄0.00
  • HTTP 403pre_consume_token_quota_failedStatuscode führt in die Irre
    Was wirklich passiert ist
    Das Konto hat noch Guthaben, aber dieser eine Key hat das Limit erreicht, das beim Erstellen gesetzt wurde. Die Meldung nennt sowohl das Restguthaben des Keys als auch den Betrag, den die Anfrage gebraucht hätte.
    Was zu tun ist
    Erhöhe oder entferne das Limit dieses Keys auf der Seite „API-Keys“, oder nimm einen Key ohne Limit. Aufladen hilft hier nicht — das Limit gilt pro Key.
    SDK wiederholt
    Nein — schlägt sofort fehl
    Am echten Endpunkt gemessen
    probes-errors.mjs: quota-exhausted
    Zurückgegebene Meldung
    token quota is not enough, token remain quota: ＄0.000002, need quota: ＄0.000074
  • HTTP 500invalid_requestStatuscode führt in die Irre
    Was wirklich passiert ist
    Im Request-Body fehlt ein Pflichtfeld, meistens messages. Ein Fehler in der Anfrage, gemeldet als Serverfehler.
    Was zu tun ist
    Die Meldung nennt das Feld wörtlich — lies also sie und nicht den Statuscode. Korrigiere den Body; ein erneuter Versuch scheitert garantiert genauso.
    SDK wiederholt
    Ja — standardmäßig zweimal
    Am echten Endpunkt gemessen
    probes-errors.mjs: missing-field
    Zurückgegebene Meldung
    field messages is required
  • HTTP 400invalid_request_errorStatuscode führt in die Irre
    Was wirklich passiert ist
    Diesen Endpunkt gibt es hier nicht: /v1/embeddings, /v1/completions und /v1/images/generations fallen alle darunter. Der Body behauptet dann, messages sei erforderlich — und zeigt damit auf etwas, das mit dem eigentlichen Problem nichts zu tun hat.
    Was zu tun ist
    Dieses Gateway bedient chat completions und den messages-Endpunkt von Anthropic. Wenn ein Framework im Hintergrund einen Embeddings-Endpunkt aufruft, braucht dieser Teil einen anderen Anbieter.
    SDK wiederholt
    Nein — schlägt sofort fehl
    Am echten Endpunkt gemessen
    probes-errors.mjs: unsupported-endpoint
    Zurückgegebene Meldung
    `messages` is required and must be a non-empty array.
  • HTTP 400leerer String
    Was wirklich passiert ist
    Der Request-Body ist kein gültiges JSON. Der Upstream verdoppelt sein eigenes Präfix „Invalid request:“, das ist rein kosmetisch.
    Was zu tun ist
    Meist ein handgeschriebener Body oder ein Quoting-Problem in der Shell. Validiere das JSON vor dem Senden und setze den Body in der Shell in einfache Anführungszeichen.
    SDK wiederholt
    Nein — schlägt sofort fehl
    Am echten Endpunkt gemessen
    probes-errors.mjs: malformed-json
    Zurückgegebene Meldung
    Invalid request: Invalid request: invalid JSON request body

Stille Fehler

Schlimmer als ein Fehler: HTTP 200

Drei Fehlerfälle geben 200 zurück, werfen keine Exception und lassen dein Programm einfach weiterlaufen. Falsch ist der Inhalt oder die Rechnung — und genau deshalb findet man sie allein so schwer.

Bilder werden angenommen und dann ignoriert

Der Upstream markiert fünf Modelle mit image_ratio. Diese Markierung ist ein Abrechnungsfaktor, keine Sehfähigkeit. Alle fünf nehmen ein Bild als Data-URL an, geben 200 zurück und antworten selbstbewusst über ein Bild, das sie nie gesehen haben — die Probe schickte ein reines grünes PNG, und keines nannte die Farbe. Das empfohlene Modell lehnt Bilder dagegen mit 400 ab, was von beiden Fehlern der harmlosere ist.

Aus der Client-Kompatibilitätsmatrix

max_completion_tokens begrenzt den Text, nicht die Rechnung

Bei einem Limit von 12 berechnete moonshotai/kimi-k2.5 261 Tokens — das 21,8-Fache. Das Abschneiden selbst greift (finish_reason=length); der Überschuss sind Reasoning-Tokens, die berechnet werden, aber nie in content auftauchen. Jede Kostenschätzung auf Basis dieses Limits liegt um denselben Faktor zu niedrig.

Aus der Client-Kompatibilitätsmatrix

Anthropic-Nachrichten-IDs haben kein msg_-Präfix

POST /v1/messages gibt eine reine Hex-ID zurück. Code, der das msg_-Präfix voraussetzt oder die ID parst, um Antworten zuzuordnen, passt nicht — obwohl der Rest des Bodys der Spezifikation entspricht.

Aus der Client-Kompatibilitätsmatrix

Parsing

Wie ein Fehler-Body aussieht

Die Hülle ist immer {"error": {...}}, aber die Feldmenge ist nicht stabil: Manche Fehler enthalten param, andere lassen es weg, und code ist häufig ein leerer String. Parse defensiv und behandle jedes Feld als optional.

401, ohne param-Feld
{"error":{"code":"","message":"Invalid token (request id: 2026090114474514374…)","type":"new_api_error"}}
404, param vorhanden, aber leer
{"error":{"message":"Invalid URL (POST /v1/fine_tuning/jobs)","type":"invalid_request_error","param":"","code":""}}

Jede Meldung endet mit einer request id, und die ist bei jedem Aufruf anders. Entferne sie, bevor du Meldungen mit dieser Seite vergleichst — und schicke sie mit, wenn du ein Problem meldest: Sie ist das Einzige, was deine konkrete Anfrage in den Logs identifiziert.

Eingrenzen

Drei Schritte, die fast alles eingrenzen

In dieser Reihenfolge. Jeder Schritt schließt eine Schicht aus, die Antwort liegt also dort, wo die Folge stehen bleibt.

  1. Zuerst Key und Route prüfen

    GET /v1/models kostet nichts und nutzt denselben Key. Ein 200 mit einer Modellliste belegt, dass Key, Netzwerk und CDN-Edge in Ordnung sind — das Problem liegt also im Request-Body, nicht bei den Zugangsdaten.

    curl -s https://api.y-api.bestvirtualgoods.com/v1/models -H "Authorization: Bearer $YAPI_KEY" | head -c 200

  2. Mit curl reproduzieren

    Damit ist das SDK aus dem Spiel. Wenn curl funktioniert und dein Code nicht, liegt der Unterschied darin, wie die Bibliothek die Anfrage baut — nicht am Gateway.

    curl -i https://api.y-api.bestvirtualgoods.com/v1/chat/completions \
  -H "Authorization: Bearer $YAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek/deepseek-v4-flash","messages":[{"role":"user","content":"hi"}]}'

  3. Beim Debuggen Wiederholungen abschalten

    Ohne Wiederholungen erscheint ein 500 oder 503, den deine eigene Anfrage verursacht, schon beim ersten Versuch statt nach zwei sinnlosen. Danach wieder einschalten — gegen echte vorübergehende Störungen sind Wiederholungen sinnvoll.

    client = OpenAI(
    base_url="https://api.y-api.bestvirtualgoods.com/v1",
    api_key=os.environ["YAPI_KEY"],
    max_retries=0,  # nur zum Debuggen
)

Nichts davon passt?

Die Statusseite zeigt mit den Prüfungen der letzten 30 Tage, ob das Gateway selbst gestört ist. Wenn dort alles grün ist und es bei dir trotzdem nicht weitergeht, ist die request id aus dem Fehler-Body das Einzige, was sich zu schicken lohnt.

Statusseite öffnen