API verwenden

API-Fehlercodes

Infercom API-Fehlercodes und HTTP-Statuscodes erklärt. Häufige Fehlertypen wie 400, 401, 429 und 500 mit Ursachen und Lösungsansätzen.

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.

{
  "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.

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.
404	Not found	Das Modell existiert nicht oder wurde abgeschaltet.	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.

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.
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.
404	`model_not_found`	Die Modell-ID existiert nicht, oder das Modell wurde abgeschaltet. Ein abgeschaltetes Modell liefert diesen Code auf `/v1/chat/completions` und `/v1/responses`. `/v1/messages` liefert denselben Status ohne `code`-Feld.	Überprüfen Sie die Modell-ID. Für ein abgeschaltetes Modell finden Sie den Nachfolger unter Veraltungen. Wiederholen Sie die Anfrage nicht.
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

Zwei Pfade verwenden diese Hülle nicht. Der Body ist weiterhin JSON, error ist dort aber ein String statt eines Objekts. Beide lassen request_id weg.

Behandeln Sie beide 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.

Defensives Parsen

def read_error(response) -> tuple[str, str | None]:
    """Gibt (message, request_id) für jede Antwortstruktur zurück."""
    try:
        body = response.json()
    except ValueError:
        # Kein JSON, etwa eine Fehlerseite eines Proxys
        # zwischen Ihrem Client und der API.
        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")