API-Fehlercodes

Die Infercom API verwendet standardmäßige HTTP-Response-Statuscodes, um anzuzeigen, ob eine API-Anfrage erfolgreich war oder fehlgeschlagen ist.

Wenn eine Anfrage fehlschlägt, antwortet die API mit einem JSON-Objekt, das Details zum Fehler enthält.

Die Fehlerhülle

Jede Fehlerantwort verwendet dieselbe Struktur. Das Fehlerdetail ist in einem error-Objekt verschachtelt, und die Antwort enthält daneben eine request_id.

Beispiel einer Fehlerantwort

{
  "error": {
    "message": "Invalid value for 'temperature': 99 is greater than the maximum of 2.",
    "type": "invalid_request_error",
    "param": "temperature",
    "code": "invalid_value"
  },
  "request_id": "dagkf1tcohtmhkppeq70"
}

Feld	Beschreibung
error.message	Eine für Menschen lesbare Erklärung des Problems.
error.type	Die Fehlerklasse, zum Beispiel invalid_request_error oder authentication_error.
error.param	Die Anfrage-Eigenschaft, die den Fehler verursacht hat. null, wenn keine einzelne Eigenschaft betroffen ist.
error.code	Ein stabiler, maschinenlesbarer Code. Siehe Fehlercode-Referenz.
request_id	Eine eindeutige Kennung der Anfrage.

Tipp

Protokollieren Sie request_id bei jeder fehlgeschlagenen Anfrage. Unser Support-Team benötigt dieses Feld, um eine Anfrage durchgängig nachzuverfolgen. Geben Sie es in jeder Meldung an, die Sie unter support.infercom.ai eröffnen.

Hinweis

/v1/messages verwendet die Anthropic-Fehlerstruktur, nicht die oben beschriebene Hülle. Der Body trägt ein "type": "error" auf oberster Ebene, und error enthält nur message und type - es gibt weder param noch code. request_id ist bei jedem Status vorhanden, trägt aber nur teilweise das Präfix req_ - bei der 401 fehlt es. Siehe Anthropic SDK-Kompatibilität.

Achtung

Drei Antworten verwenden diese Hülle nicht, und eine davon ist überhaupt kein JSON. Lesen Sie Abweichende Fehlerformate, bevor Sie Ihre Fehlerbehandlung schreiben.

Fehlerkategorien

Verwenden Sie die folgende Tabelle, um die verschiedenen Fehlerkategorien zu verstehen.

HTTP-Status	Kategorie	Beschreibung	Vorschlag
400	Bad request	Der Server konnte die Anfrage aufgrund ungültiger Syntax oder Eingabewerte nicht verarbeiten.	Überprüfen Sie die API-Anfrage-Syntax und Parameter.
401	Unauthorized	Authentifizierungsdaten fehlen oder sind ungültig.	Stellen Sie sicher, dass ein gültiger API-Schlüssel/Token enthalten ist.
408	Request timeout	Der Server hat die Anfrage aufgrund übermäßiger Verarbeitungszeit beendet.	Wiederholen Sie die Anfrage mit optimierter Payload.
410	Gone	Das angeforderte Modell ist nicht mehr verfügbar (veraltet oder entfernt).	Verwenden Sie ein aktuell unterstütztes Modell.
422	Unprocessable entity	Die Anfrage ist korrekt aufgebaut, das Modell ist jedoch in Ihrem Plan nicht aktiviert.	Verwenden Sie ein Modell, das für Ihr Abonnement gelistet ist.
429	Too many requests	Ratenlimit für Ihre Abonnementstufe überschritten.	Implementieren Sie Ratenbegrenzung oder upgraden Sie die Stufe.
429	Queue Full	Zu viele Anfragen sind derzeit in Bearbeitung; der Server hat die Anfrage abgelehnt.	Wiederholen Sie nach kurzer Verzögerung oder reduzieren Sie die Parallelität.
500	Something went wrong	Ein serverseitiger Fehler ist aufgetreten.	Wiederholen Sie später oder kontaktieren Sie den Support, falls anhaltend.
503	Maintenance	Das Modell ist aufgrund von Wartungsarbeiten vorübergehend nicht verfügbar.	Versuchen Sie es nach einiger Zeit erneut.

Tipp

Bei 500- oder 503-Fehlern prüfen Sie die Infercom Status-Seite auf aktuelle Vorfälle oder geplante Wartungsarbeiten, bevor Sie den Support kontaktieren.

Fehlercode-Referenz

Verwenden Sie die folgende Tabelle, um Fehler programmatisch zu verstehen und zu beheben.

HTTP-Status	Fehlercode	Beschreibung	Vorschlag
400	context_length_exceeded	Eingabe-/Ausgabe-Tokens überschreiten die Modell-Kontextgrenzen.	Reduzieren Sie Prompt- und Antwortlänge, um innerhalb der Modellgrenzen zu bleiben.
	invalid_type	Parametertyp-Nichtübereinstimmung (z.B. int erwartet, aber float erhalten).	Überprüfen Sie die erwarteten Parametertypen und korrigieren Sie die Eingabe.
	decimal_above_max_value	Dezimalwert überschreitet das zulässige Maximum.	Passen Sie den Wert an, um in den zulässigen Bereich zu fallen.
	decimal_below_min_value	Dezimalwert liegt unter dem zulässigen Minimum.	Erhöhen Sie den Wert, um die Mindestschwelle zu erfüllen.
	integer_above_max_value	Ganzzahlwert überschreitet das zulässige Maximum.	Geben Sie eine kleinere Ganzzahl innerhalb des gültigen Bereichs an.
	invalid_value	Parameterwert liegt außerhalb des zulässigen Bereichs.	Prüfen Sie den zulässigen Bereich für diesen Parameter und senden Sie erneut.
	unknown_parameter	Der Endpunkt akzeptiert diesen Parameter nicht.	Entfernen Sie den Parameter. Prüfen Sie die Referenzseite des Endpunkts auf die akzeptierten Parameter.
	model_not_supported	Das Modell existiert, bedient diesen Endpunkt aber nicht.	Verwenden Sie ein Modell, das für diesen Endpunkt gelistet ist. Siehe Unterstützte Modelle.
	unsupported_model	Das Modell wird von /v1/responses nicht bedient.	Verwenden Sie /v1/chat/completions oder ein Modell, das die Responses API bedient.
	model_not_found	Die angegebene Modell-ID existiert nicht.	Überprüfen Sie die Modell-ID und stellen Sie sicher, dass sie in Ihrem Abonnement verfügbar ist.
401	invalid_authentication	Ungültiger oder abgelaufener API-Schlüssel.	Generieren und verwenden Sie einen gültigen API-Schlüssel aus dem Infercom-Portal.
	invalid_api_key	Der API-Schlüssel ist falsch oder wurde widerrufen.	Erstellen Sie einen neuen Schlüssel unter cloud.infercom.ai und aktualisieren Sie Ihren Client.
408	request_timeout	Anfrage aufgrund von Serverlast oder Latenz abgelaufen.	Wiederholen Sie mit einer kleineren oder optimierten Anfrage-Payload. Erwägen Sie außerdem ein Upgrade auf eine höhere Abonnementstufe.
410	model_deprecated	Das angeforderte Modell wurde veraltet und ist nicht mehr verfügbar. Kein Endpunkt gibt diesen Code derzeit zurück. /v1/responses liefert internal_error, /v1/messages liefert kein code-Feld, und /v1/chat/completions liefert einen Klartext-Body ganz ohne Code. Eine Korrektur ist bei unserem Plattformanbieter in Arbeit.	Verwenden Sie ein aktuell unterstütztes Modell, das in der Dokumentation aufgeführt ist. Wiederholen Sie die Anfrage nicht - eine 410 ist dauerhaft.
422	model_not_in_plan	Das Modell existiert, ist aber in Ihrem Plan nicht aktiviert. Wird von /v1/chat/completions und /v1/messages zurückgegeben. Die übrigen Endpunkte geben für denselben Fall 400 zurück.	Verwenden Sie ein Modell, das für Ihr Abonnement gelistet ist, oder wenden Sie sich an den Support.
429	insufficient_quota	Ratenlimit überschritten.	Upgraden Sie Ihren Plan für höheres Kontingent.
429	queue_full	Zu viele laufende Anfragen; Server hat die Anfrage abgelehnt.	Wiederholen Sie nach einer Verzögerung oder reduzieren Sie die Anfragehäufigkeit.
500	internal_server_error	Ein unerwarteter serverseitiger Fehler ist aufgetreten.	Wiederholen Sie später. Wenn das Problem weiterhin besteht, kontaktieren Sie den Support.
503	maintenance	Modell ist aufgrund von Wartungsarbeiten vorübergehend nicht verfügbar.	Versuchen Sie es nach einiger Zeit erneut oder prüfen Sie Wartungsankündigungen.

Abweichende Fehlerformate

Drei Pfade verwenden diese Hülle nicht. Bei zweien ist der Body weiterhin JSON, error ist dort aber ein String statt eines Objekts. Beim dritten ist der Body überhaupt kein JSON. Alle drei lassen request_id weg.

Behandeln Sie alle drei Strukturen, bevor Sie error.message lesen.

Fehlerhafte Bilddaten

Wird bei Vision-Anfragen zurückgegeben, wenn die API das Bild nicht dekodieren kann. HTTP 400.

{
  "error": "Unable to decode image: cannot identify image file <_io.BytesIO object at 0x...>",
  "error_code": null,
  "error_param": null,
  "error_type": "invalid_request_error"
}

Ein erzwungenes tool_choice, das das Modell nicht erfüllt

Wird bei Function Calling-Anfragen zurückgegeben, wenn Sie eine bestimmte Funktion erzwingen und das Modell keinen gültigen Aufruf erzeugt. HTTP 400.

{
  "error": "Specified tool_choice with function name \"book_flight\", but the model output contains zero valid function call.",
  "error_code": null,
  "error_model_output": "I can help you book a flight from Munich to Lisbon...",
  "error_type": "Invalid function calling output."
}

Dieser Body enthält ein Feld, das die Hülle nicht definiert: error_model_output. Es trägt den Text, den das Modell anstelle des Tool-Aufrufs erzeugt hat. Beachten Sie außerdem, dass error_type hier einen Satz enthält und keinen Code wie invalid_request_error.

Ein abgeschaltetes Modell auf /v1/chat/completions

Wird zurückgegeben, wenn das angefragte Modell veraltet und entfernt wurde. HTTP 410.

Diese Antwort ist kein JSON. Sie wird als content-type: text/plain; charset=utf-8 ausgeliefert, mit einem einfachen Satz als vollständigem Body:

The requested model (MiniMax-M2.5) is not available on SambaNova Cloud. For more information, please visit https://docs.sambanova.ai/cloud/docs/resources/deprecations. For further inquiries, please contact our support team at help@sambanova.ai.

Wird dieser Body als JSON geparst, entsteht ein Decode-Fehler. Prüfen Sie den content-type der Antwort, oder fangen Sie den Decode-Fehler ab, bevor Sie den Body lesen.

Hinweis

Offizielle SDKs verkraften dies bereits. Das OpenAI Python SDK löst openai.APIStatusError mit status_code 410 aus und legt den Satz in .body ab. Betroffen sind Clients, die .json() selbst auf der rohen Antwort aufrufen - requests etwa löst requests.exceptions.JSONDecodeError aus.

Derselbe Fall gibt auf /v1/responses und /v1/messages JSON zurück.

Achtung

Wiederholen Sie eine 410 nicht. Der Zustand ist dauerhaft. Ändern Sie stattdessen die Modell-ID. Aktuelle Nachfolger finden Sie unter Veraltungen.

Defensives Parsen

def read_error(response) -> tuple[str, str | None]:
    """Gibt (message, request_id) für alle drei Antwortstrukturen zurück."""
    try:
        body = response.json()
    except ValueError:
        # Kein JSON. Manche Fehler, etwa ein abgeschaltetes Modell auf
        # /v1/chat/completions, liefern einen Klartext-Body.
        return response.text.strip(), None

    err = body.get("error")
    if isinstance(err, str):
        return err, None
    return err.get("message", "unknown error"), body.get("request_id")