Die Ottili AI API verwendet standardisierte HTTP-Statuscodes und gibt bei Fehlern einen maschinenlesbaren Fehlerkörper zurück.
Fehlerkörper
{
"code": "DEVELOPER_SCOPE_REQUIRED",
"message": "API key is missing the required Ottili ONE scope.",
"detail": {
"requiredScopes": ["ai:read"],
"grantedScopes": ["developer:read"]
}
}| Feld | Beschreibung |
|---|---|
code | Stabiler, maschinenlesbarer Fehlercode. |
message | Menschengelesene Zusammenfassung. |
detail | Optionaler Kontext (Scopes, Kennungen, Limits). |
Häufige Codes
| Code | HTTP | Bedeutung |
|---|---|---|
UNAUTHORIZED | 401 | Fehlender oder ungültiger Authorization-Header oder abgelaufenes Token. |
DEVELOPER_SCOPE_REQUIRED | 403 | API-Key fehlt der erforderliche Scope. |
COMPANY_CONTEXT_NOT_FOUND | 404 | Company-Slug nicht gefunden oder nicht zugreifbar. |
WORKSPACE_CONTEXT_NOT_FOUND | 404 | Workspace-Slug nicht gefunden oder nicht zugreifbar. |
COMPANY_INACTIVE / WORKSPACE_INACTIVE | 403 | Company oder Workspace gesperrt oder archiviert. |
MODEL_NOT_AVAILABLE | 409 | Gepinntes Modell für Tarif/Region nicht verfügbar. |
CAPABILITY_UNSUPPORTED | 422 | Modell fehlt die angeforderte Fähigkeit (z. B. strukturierte Ausgaben). |
VALIDATION_ERROR | 422 | Anfragekörper bestand Schema-Validierung nicht. |
USAGE_LIMIT_EXCEEDED | 403 | Credits oder Monatsbudget aufgebraucht. |
RATE_LIMIT_EXCEEDED | 429 | Rate Limit überschritten; siehe Retry-After. |
Fehlerbehebung
401— prüfen Sie denAuthorization: Bearer ott_...-Header und dass der Key nicht rotiert wurde.403Scope — rufen Sie den Identitäts-Endpunkt auf, umgrantedScopeszu prüfen, und fordern Sie den fehlenden Scope bei Ihrem Admin an.404Company/Workspace — bestätigen Sie dieX-Platform-Company/X-Platform-Workspace-Slugs über den Identitäts-Endpunkt.429— beachten SieRetry-Afterund ergänzen Sie exponentiellen Backoff.
Dieselben Fehlerkonventionen gelten über die gesamte öffentliche Entwickler-Oberfläche, sodass ein Client AI- und Nicht-AI-Endpunkte einheitlich behandeln kann.
War dieser Artikel hilfreich?