Fehlerreferenz

Standardisiertes Fehlerformat und die häufigsten Codes.

Format

Jeder Fehler folgt derselben JSON-Struktur, unabhängig vom Endpunkt:

json

{
  "error": {
    "code": "insufficient_credits",
    "message": "Solde de credits insuffisant ou budget mensuel du projet depasse.",
    "request_id": "9480fe92-f68e-4731-b98e-d35a5e8b9819",
    "details": {}
  }
}

request_id identifiziert die Anfrage durchgängig über alle Dienste hinweg — nützlich anzugeben, wenn Sie uns wegen eines unerwarteten Fehlers kontaktieren.

Häufige Codes

HTTP	Code	Bedeutung
401	missing_api_key	Authorization-Header fehlt.
401	invalid_api_key	Ungültiger, widerrufener oder abgelaufener API-Schlüssel.
403	insufficient_scope	Der Schlüssel hat nicht den erforderlichen Scope für diese Kategorie.
403	not_a_member	Sie gehören nicht zu dieser Organisation.
403	csrf_check_failed	Sicherheits-Header fehlt (Sitzungscookie, nicht relevant bei API-Schlüssel-Nutzung).
404	model_not_found	routing_strategy "manual" mit einem im Katalog unbekannten model.
404	no_model_available	Kein Modell entspricht den angeforderten Kriterien.
402	insufficient_credits	Unzureichendes Guthaben oder monatliches Projektbudget überschritten.
409	conflict	Zustand nicht kompatibel mit der Aktion (z. B. Agentenkonversation nicht idle).
422	validation_error	Ungültiger Anfragetext (fehlendes Feld, falscher Typ...).
429	rate_limit_exceeded	Zu viele Anfragen für diesen Schlüssel — siehe Ratenlimits.
503	all_providers_unavailable	Alle Kandidatenanbieter sind fehlgeschlagen (siehe Routing & Failover).

In den SDKs

Die offiziellen SDKs wandeln jeden HTTP-Statusbereich in eine typisierte Fehlerklasse um (AuthenticationError, PermissionDeniedError, NotFoundError, InsufficientCreditsError, ConflictError, ValidationError, RateLimitError, ServerError), die alle zusätzlich zur Nachricht .code, .status, .requestId und .details bereitstellen. Siehe JavaScript-SDK / Python-SDK.