Fehlercodes & Grenzen.
Aufbau aller Fehlerantworten des Gateways, Status-zu-type-Zuordnung, Retry-After, Größen-, Zeit- und Ratenlimits sowie alle Fehlercodes.
Fehlerformat & Behandlung.
Jeden Fehler — auch Fehler eines Anbieters — beantwortet das Gateway mit einem einheitlichen JSON-Objekt unter error, bestehend aus stabilem code, vom HTTP-Status abgeleitetem type und englischem message-Text (bei Streaming-Fehlern nach gesendetem Status 200 zusätzlich retry_after in Sekunden). Prüfe im Code immer error.code, nicht message. Ab Status 500 endet message auf (request id <id>), passend zu den Headern x-request-id und request-id.
{
"error": {
"type": "insufficient_quota",
"code": "key_budget_exhausted",
"message": "This API key has reached its spending limit.",
"param": null
}
}{
"type": "error",
"error": {
"type": "billing_error",
"code": "key_budget_exhausted",
"message": "This API key has reached its spending limit."
},
"request_id": "4f1c9a20"
}HTTP/1.1 429 Too Many Requests
content-type: application/json
retry-after: 5
x-noirdoc-provider: ionos
x-request-id: 4f1c9a20
{
"error": {
"type": "rate_limit_error",
"code": "resource_exhausted",
"message": "The requested resource is temporarily at capacity.",
"param": null
}
}OpenAI-Endpunkte setzen immer “param”: null; /v1/messages und
/v1/skills liefern die Anthropic-Hülle mit request_id. Nur auf
/v1/files wählt x-api-key das Anthropic-Format und
Authorization: Bearer bzw. api-key das OpenAI-Format.
Zuordnung von Status zu type
| Status | type bei OpenAI-Endpunkten | type bei /v1/messages und /v1/skills |
|---|---|---|
| 400, 405, 409, 422 | invalid_request_error | invalid_request_error |
| 401 | authentication_error | authentication_error |
| 402 | insufficient_quota | billing_error |
| 403 | permission_error | permission_error |
| 404 | not_found_error | not_found_error |
| 413 | invalid_request_error | request_too_large |
| 429 | rate_limit_error | rate_limit_error |
| 500, 502 | server_error | api_error |
| 503 | server_error | overloaded_error |
| 504 | server_error | timeout_error |
| 529 | nicht vergeben | overloaded_error |
Fehler des Anbieters & BYOK
Antwortet ein Anbieter mit einem Fehler, normiert das Gateway die Antwort. Bei Kapazitätsproblemen oder Überlast versucht es zuvor bis zu drei Anbieter desselben Modells (Failover) und sperrt einen mit 429 antwortenden verwalteten Anbieter vorübergehend für die Dauer aus dessen Retry-After (1–60 s, ohne Header 10 s, bei erschöpftem Kontingent 60 s):
| Antwort des Anbieters | Verwalteter Anbieter | Eigener Schlüssel (BYOK) |
|---|---|---|
| 429 oder 402 (Kapazität / Kontingent) | 429 resource_exhausted mit Retry-After (nach Failover) | provider_rejected_request mit Status & Meldung des Anbieters (bei 429 mit Retry-After 1–60 s, sonst 5 s) |
| 503 oder 529 (Überlast) | provider_overloaded mit Retry-After (Status 503 auf OpenAI-Routen, 529 auf /v1/messages und /v1/skills) | provider_overloaded mit Retry-After |
| 400, 404, 422 und übrige 4xx-Anfragefehler | Sofort provider_rejected_request mit Status und bereinigter Meldung des Anbieters (höchstens 500 Zeichen; ohne JSON-Body "The provider rejected the request."; 4xx-Meldungstexte werden nicht protokolliert) | Sofort provider_rejected_request mit Status und Meldung des Anbieters |
| 401, 403 oder übrige 5xx | 502 provider_error (fester Text) | Bei 401/403 provider_rejected_request; bei 5xx 502 provider_error |
Die Antwort enthält ausschließlich die vom Gateway gesetzten Header (Content-Type, X-Noirdoc-Provider, X-Noirdoc-Shield, X-Noirdoc-Masked, X-Request-ID, Request-ID, Retry-After sowie Content-Disposition bei Audio- und Datei-Downloads); interne Anbieter-Header wie x-ratelimit-* entfallen.
Retry-After & Stream-Abbrüche
| Status | Code | Retry-After (Sekunden) |
|---|---|---|
| 429 | starter_rate_limit_exceeded | Restzeit der laufenden Minute (1–60 s) oder des laufenden UTC-Tages |
| 429 | resource_exhausted | Wert des Anbieters zwischen 1 und 60 s, sonst 5 s |
| 503, 529 | provider_overloaded | Wert des Anbieters zwischen 1 und 60 s, sonst 5 s |
| 503 | capacity_exhausted | Geschätzte Sekunden bis ein Anbieter frei wird (höchstens 60 s), sonst 5 s |
| 503 | shield_unavailable, service_overloaded, forwarding_pool_exhausted, ownership_check_unavailable, provider_auth_unavailable | 5 s |
| 503 | masking_unavailable (klassische Maskierung bis 30.11.2026) | 10 s |
| 504 | provider_timeout | 10 s |
Scheitert ein Stream, nachdem Status 200 bereits gesendet wurde (etwa nach : ping-Keep-Alives oder bei einem Abbruch mitten im Stream mit stream_interrupted bzw. gateway_restarting und "retry_after": 5), beendet das Gateway den Stream mit einem Fehler-Event im Endpunktformat:
/v1/chat/completions:data: {"error": {"type": "...", "code": "stream_interrupted", "message": "...", "param": null}}gefolgt vondata: [DONE](löst in OpenAI-SDKs einenAPIErroraus)./v1/responses: SSE-Eventerrorgefolgt vondata: [DONE](im OpenAI-Python-SDKevent.type == "error"in der Schleife prüfen)./v1/messages: SSE-Eventerrorgefolgt vonevent: message_stop.
import os
import httpx
RETRYABLE = {
"starter_rate_limit_exceeded",
"resource_exhausted",
"provider_overloaded",
"capacity_exhausted",
"shield_unavailable",
"service_overloaded",
"forwarding_pool_exhausted",
"provider_timeout",
}
res = httpx.post(
"https://api.noirdoc.de/v1/chat/completions",
headers={"Authorization": f"Bearer {os.environ['NOIRDOC_API_KEY']}"},
json={
"model": "qwen3.8-27b",
"messages": [{"role": "user", "content": "Hallo"}],
},
timeout=400,
)
if res.status_code >= 400:
err = res.json().get("error", {})
code = err.get("code", "unknown")
if code in RETRYABLE:
wait = int(res.headers.get("retry-after", 5))
print(f"Erneut senden nach {wait} s ({code}).")
else:
print(f"Fehler {code}: {err.get('message')}")const RETRYABLE = new Set([
"starter_rate_limit_exceeded",
"resource_exhausted",
"provider_overloaded",
"capacity_exhausted",
"shield_unavailable",
"service_overloaded",
"forwarding_pool_exhausted",
"provider_timeout",
]);
const res = await fetch("https://api.noirdoc.de/v1/chat/completions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.NOIRDOC_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "qwen3.8-27b",
messages: [{ role: "user", content: "Hallo" }],
}),
});
if (!res.ok) {
const body = await res.json().catch(() => null);
const code = body?.error?.code ?? "unknown";
if (RETRYABLE.has(code)) {
const wait = Number(res.headers.get("retry-after") ?? 5);
console.log(`Erneut senden nach ${wait} s (${code}).`);
} else {
console.log(`Fehler ${code}: ${body?.error?.message ?? res.status}`);
}
}Grenzen des Gateways.
Diese Tabelle fasst alle Größen-, Zeit-, Raten- und Mengengrenzen zusammen, die das Gateway selbst durchsetzt (1 MB = 1024 × 1024 Byte). Engere modellspezifische Grenzen eines Anbieters (etwa die Kontextlänge) meldet das Gateway als provider_rejected_request.
| Bereich / Endpunkt | Grenze | Fehler bei Überschreitung |
|---|---|---|
Body /v1/files & /v1/skills (inkl. Unterpfade) | höchstens 600 MB | 413 request_too_large |
Body übrige /v1/*-Endpunkte | höchstens 160 MB | 413 request_too_large |
Body /v1/audio/transcriptions (Multipart gesamt) | höchstens 26 MB | 413 request_too_large |
| Verbindungsaufbau zum Anbieter | 10 s je Anbieter | 504 provider_timeout |
| Antwortzeit Anbieter (ohne Stream / mit Stream) | 120 s je Anbieter / 600 s gesamt (: ping alle 15 s) | 504 provider_timeout |
| Failover-Versuche je Anfrage | höchstens 3 Anbieter derselben Art (kein Mix aus BYOK und verwaltet; 3xx unverändert) | Fehler des letzten Versuchs |
| Warten auf freien Anbieter / Verbindungspool | bis zu 10 s / Pool-Limit | 503 capacity_exhausted / 503 forwarding_pool_exhausted |
| Startguthaben: Modellauswahl (vor erster Aufladung) | nur für das Startguthaben freigegebene Modelle auf verwalteten Anbietern | 403 starter_model_not_allowed |
| Startguthaben: Rate Limits (vor erster Aufladung) | 5 Anfragen/Minute und 25 Anfragen/Tag (UTC) je Organisation auf verwalteten Anbietern (abgelehnte Anfragen aus Minutenlimit oder starter_model_not_allowed zählen nicht auf das Tageslimit) | 429 starter_rate_limit_exceeded mit Retry-After |
| Rate Limits nach erster bestätigter Aufladung / Rechnung / BYOK | keine kunden- oder schlüsselbezogenen Rate Limits durch das Gateway (Guthaben & Budgets begrenzen Kosten über Status 402) | — |
| Noirdoc Shield: geprüfter Text je Gateway-Anfrage | höchstens 4 MiB kodierter Text | 413 shield_input_too_large |
| Eingebettete UTF-8-Textdateien unter Shield | unter 4 MiB dekodiert (ab 4 MiB sowie Binärdateien, Bilder, Audio und file_id: ohne enforced X-Noirdoc-Shield: partial; redacted=<n>; klassische Dateianalyse bis 30.11.2026: Standard 25 MB je Datei bzw. 422 file_unprocessable) | 422 shield_uninspectable_content (enforced), 403 file_content_not_allowed (Schalter aus) |
POST /v1/shield/inspect: input | 1 bis 64 nicht leere Strings, zusammen höchstens 256 KB UTF-8 | 400 invalid_request_error |
Shield custom_patterns | höchstens 100 Muster, je 2 bis 256 Zeichen (re:-Regex oder literaler Begriff) | 400 invalid_request_error |
POST /v1/rerank | nicht leerer String query, 1 bis 1.000 Strings in documents, optional top_n >= 1 (nur Text) | 400 invalid_rerank_request |
POST /v1/audio/speech | input 1 bis 4.096 Zeichen, nicht leerer String voice | 400 invalid_tts_request |
POST /v1/images/generations | nicht leerer prompt, n 1 bis 10 (Standard 1), size BREITExHÖHE 1 bis 2048 px (Standard 1024x1024, kein "auto"), gesamt höchstens 16 MP aufgerundet in 1024 × 1024-Einheiten | 400 invalid_image_request |
Request-Tags (X-Noirdoc-Tags & /v1/tags, Preview) | 1 bis 5 Komma-getrennte Tags je Anfrage, je 1 bis 64 Zeichen (^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,63}$, nicht _default), höchstens 1.000 Tags je Organisation | 400 invalid_request_tags, 403 tag_limit_exceeded |
Alle Fehlercodes.
Nach HTTP-Status gruppierte Referenz aller Gateway-Fehlercodes. Jede Zeile besitzt einen eigenen Anker wie #key_budget_exhausted:
| Code | Bedeutung | Abhilfe |
|---|---|---|
| 400 Ungültige Anfrage | ||
invalid_request_path | Der Pfad enthält ein Punkt-Segment (. oder ..), ein %, einen Backslash oder ein Steuerzeichen. | Sende den Pfad ohne Punkt-Segmente und ohne kodierte Zeichen, zum Beispiel /v1/chat/completions. |
model_required | Die Anfrage nennt kein Modell (model im Body, bei /v1/audio/transcriptions im Formularfeld). | Gib eine Modell-ID aus GET /v1/models an. |
wrong_endpoint_for_model | Das Modell gehört zu einer anderen Endpunkt-Familie oder einem anderen API-Format als der aufgerufene Endpunkt. | Rufe das Modell über den passenden Endpunkt auf, zum Beispiel ein Embedding-Modell über /v1/embeddings. |
streaming_not_supported_for_endpoint | Die Anfrage verlangt Streaming, der Endpunkt unterstützt es aber nicht. | Entferne stream aus der Anfrage. |
invalid_request_body | Der Body ist kein JSON-Objekt oder nicht in UTF-8 kodiert. | Sende den Body als JSON-Objekt in UTF-8 mit Content-Type: application/json und prüfe das in message genannte Feld. |
invalid_request_error | Ein Parameter auf /v1/shield/inspect oder /v1/shield/policy ist ungültig (etwa leerer oder über 256 KB großer input, mehr als 64 Einträge, unbekannte Regel oder ungültiger Sperrbegriff), oder der JSON-Body ist für die Shield-Extraktion zu tief verschachtelt. | Prüfe message und passe input (1 bis 64 nicht leere Strings, zusammen höchstens 256 KB), rules, mode oder custom_patterns gemäß der Referenz unter /v1/shield an. |
provider_rejected_request | Der Anbieter hat die Anfrage selbst abgelehnt, etwa wegen eines ungültigen Parameters oder eines zu langen Kontexts. Die Antwort trägt den Statuscode des Anbieters (400, 404, 409, 413, 422 oder einen anderen Statuscode 4xx außer 401, 402, 403 und 429), und message enthält die Meldung des Anbieters in gekürzter und bereinigter Form, höchstens 500 Zeichen. Auf Routen mit eigenem Anbieter-Schlüssel (BYOK) meldet das Gateway auch die Statuscodes 401, 402, 403 und 429 des Anbieters so, weil Schlüssel, Guthaben und Kontingent dem Kunden gehören; bei 429 kommt Retry-After hinzu. | Korrigiere die Anfrage anhand der Meldung. Eine unveränderte Wiederholung scheitert erneut. X-Noirdoc-Provider nennt den Anbieter. |
invalid_image_request | prompt, n oder size liegt außerhalb der Grenzen des Gateways; message nennt den Parameter. | Korrigiere den genannten Parameter. Teile große Bildanfragen in mehrere Anfragen auf. |
invalid_rerank_request | query ist kein nicht leerer String, documents ist keine Liste von 1 bis 1.000 Strings oder top_n ist keine ganze Zahl ab 1; message nennt das Feld. | Sende query und jedes Dokument als reinen Text, höchstens 1.000 Dokumente je Anfrage und top_n als ganze Zahl ab 1. |
invalid_tts_request | input oder voice fehlt oder ist leer, oder input ist zu lang. | Sende input und voice als nicht leere Strings und kürze input auf höchstens 4.096 Zeichen. |
invalid_multipart_body | Der Body ist kein gültiges multipart/form-data, oder model, stream bzw. response_format kommt mehrfach vor. | Sende die Audiodatei als Multipart-Formular mit jedem dieser Felder höchstens einmal. |
invalid_request_tags | Der Header X-Noirdoc-Tags oder der Tag-Name im Pfad unter /v1/tags ist leer, enthält mehr als 5 Tags oder entspricht nicht dem Format ^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,63}$. | Sende 1 bis 5 durch Komma getrennte Tag-Namen aus je 1 bis 64 Zeichen (a-z, A-Z, 0-9 und _ . : -, erstes Zeichen alphanumerisch). |
| 401 Nicht authentifiziert | ||
invalid_api_key | Der Schlüssel fehlt, ist ungültig oder deaktiviert, oder die Organisation ist nicht aktiv. | Sende einen gültigen Schlüssel, der mit px- beginnt, im Header Authorization: Bearer, x-api-key oder api-key (Azure-Stil). Prüfe den Schlüssel unter Models → API-Schlüssel. |
| 402 Guthaben oder Budget | ||
insufficient_credit | Das Guthaben der Organisation ist aufgebraucht oder kleiner als die geschätzten Höchstkosten der Anfrage (einschließlich Noirdoc Shield, auch auf BYOK-Routen mit aktivem Shield). | Lade unter Abrechnung → Aufladen Guthaben auf, oder senke max_tokens bzw. kürze die Eingabe. |
key_budget_exhausted | Das Budget dieses Schlüssels ist für den laufenden Zeitraum aufgebraucht oder reicht für die geschätzten Kosten der Anfrage nicht aus. | Erhöhe das Ausgabenlimit unter Models → API-Schlüssel, senke max_tokens oder warte auf die nächste Rücksetzung. |
tag_budget_exhausted | Das Budget eines in X-Noirdoc-Tags genannten Tags ist für den laufenden Zeitraum aufgebraucht oder reicht für die geschätzten Kosten der Anfrage nicht aus; message nennt das Tag. | Erhöhe das Ausgabenlimit des Tags unter Models → Tags oder über /v1/tags, senke max_tokens oder warte auf die nächste Rücksetzung. |
| 403 Nicht erlaubt | ||
endpoint_not_available_on_platform | Der Aufruf würde Daten aus dem gemeinsamen Konto eines von Noirdoc verwalteten Anbieters lesen und ist dort gesperrt. | Verbinde unter Models → Provider einen eigenen Anbieter-Schlüssel (BYOK) für diesen Endpunkt. |
stored_responses_disabled | Die Anfrage würde Eingabe und Antwort beim verwalteten Anbieter speichern (store, previous_response_id oder eine Unterroute für gespeicherte Antworten), und deine Organisation hat die Speicherung beim Anbieter nicht eingeschaltet. | Sende den Verlauf in jeder Anfrage mit, lass Admins unter Models → Shield die Option „Responses-API Speicherung beim Anbieter erlauben“ einschalten oder verwende einen eigenen Anbieter-Schlüssel (BYOK). |
reference_not_available_on_platform | Der Body verweist auf Objekte beim Anbieter (etwa conversation, prompt.id oder vector_store_ids), deren Besitz das Gateway bei verwalteten Anbietern nicht prüfen kann. | Entferne die in message genannten Felder oder verwende einen eigenen Anbieter-Schlüssel (BYOK). |
model_not_allowed_for_key | Das Modell gehört nicht zu den erlaubten Modellen dieses Schlüssels. | Wähle ein Modell aus GET /v1/models oder erweitere die erlaubten Modelle unter Models → API-Schlüssel. |
provider_not_allowed_for_tenant | Die Organisation gilt als Berufsgeheimnisträger (§ 203 StGB); das schließt jeden Anbieter aus, der dieses Modell anbietet. | Wähle ein Modell aus GET /v1/models. Die Liste enthält nur Modelle mit erlaubten Anbietern. |
provider_not_allowed_for_key | Die Einschränkungen des Schlüssels (Anbieter, Datenresidenz, CLOUD Act, § 203) schließen jeden Anbieter dieses Modells aus. | Wähle ein Modell aus GET /v1/models oder lockere die Einschränkungen unter Models → API-Schlüssel. |
starter_model_not_allowed | Die Organisation nutzt noch ausschließlich das Startguthaben, und das Modell bzw. sein verwalteter Anbieter ist im Startguthaben nicht freigegeben. | Wähle ein im Startguthaben freigegebenes Modell aus GET /v1/models, verbinde unter Models → BYOK einen eigenen Anbieter-Schlüssel oder lade unter Abrechnung → Aufladen einmalig Guthaben auf, um sofort alle verwalteten Modelle freizuschalten. |
shield_violation | Noirdoc Shield hat die Anfrage vor der Weiterleitung an den Anbieter blockiert, weil ein aktiver Schutzfilter mit der Aktion block angeschlagen hat; message nennt die ausgelöste Regel (secrets, pii, ner, injection oder custom). | Entferne den auslösenden Inhalt aus der Anfrage oder stelle die Regel unter Models → Shield bzw. über /v1/shield/policy auf redact oder off (bei injection nur off). |
shield_policy_enforced | Die Shield-Richtlinie der Organisation steht auf enforced, und die Anfrage auf /v1/shield/inspect versucht über policy eine aktive Regel abzuschwächen oder eigene Sperrbegriffe wegzulassen. | Lass policy weg oder übergib nur gleich strenge oder strengere Regeln (redact zu block oder zusätzliche custom_patterns). |
masking_not_supported_for_endpoint | Der Endpunkt unterstützt weder Noirdoc Shield noch die klassische Maskierung, aber die Richtlinie steht auf enforced oder die Anfrage sendet X-Noirdoc-Mask: on (auf /v1/images/generations auch X-Noirdoc-Shield: on). Während der Übergangsfrist der klassischen Maskierung bis zum 30.11.2026 betrifft das auf Bestandsorganisationen ohne Shield auch /v1/embeddings und /v1/rerank. | Lass den Header weg. Bei enforced kann ein Admin die Standard-Einstellung unter Models → Shield anpassen; für /v1/embeddings und /v1/rerank genügt die Umstellung auf Noirdoc Shield. |
file_content_not_allowed | Die Anfrage enthält Dateien, Bilder oder Audio, und die Organisation lässt keine Dateiinhalte zu. | Sende die Anfrage ohne Dateien, oder lass einen Admin unter Models → Shield unter Erweiterte Einstellungen die Option „Dateianhänge und Bilder in Anfragen erlauben“ einschalten. |
file_pii_blocked | Eine Datei enthält personenbezogene Daten, und die klassische Dateianalyse der Organisation (Übergangsbetrieb bis 30.11.2026) steht auf block oder unter enforced auf detect_only. | Entferne die personenbezogenen Daten aus der Datei oder stelle unter Models → Shield auf Noirdoc Shield um. |
model_not_billable | Für das Modell ist kein vollständiger Preis hinterlegt, deshalb lässt es sich mit Guthaben nicht nutzen. | Wähle ein anderes Modell oder wende dich an den Support. |
request_tags_disabled | Die Anfrage sendet X-Noirdoc-Tags oder ruft /v1/tags auf, aber Request-Tags (Preview) sind für diese Organisation nicht freigeschaltet. | Entferne den Header X-Noirdoc-Tags oder lass Request-Tags für deine Organisation freischalten. |
tag_not_found | Das genannte Tag existiert nicht. Bei Anfragen mit X-Noirdoc-Tags ist die automatische Tag-Anlage ausgeschaltet (Statuscode 403); auf /v1/tags/{name} antwortet das Gateway mit Statuscode 404. | Lege das Tag unter Models → Tags oder per POST /v1/tags an, oder schalte in der Standard-Tag-Vorlage die automatische Anlage ein. |
tag_disabled | Ein in X-Noirdoc-Tags genanntes Tag ist deaktiviert. | Aktiviere das Tag unter Models → Tags oder über /v1/tags, oder entferne es aus X-Noirdoc-Tags. |
tag_limit_exceeded | Die Organisation hat die Obergrenze von 1.000 Request-Tags erreicht. | Lösche nicht mehr benötigte Tags ohne Abrechnungshistorie unter Models → Tags oder über DELETE /v1/tags/{name}, oder verwende bestehende Tags weiter. |
insufficient_key_permissions | Dem API-Schlüssel fehlt die Berechtigung für /v1/tags (can_manage_tags) oder /v1/shield/policy (can_manage_shield), ein Schlüssel mit fest aktiviertem Shield (shield_mode: on) versucht die Shield-Richtlinie oder shield_mode eines Tags abzuschwächen, oder das Tag soll weiter reichende Modelle, Anbieter oder Compliance-Regeln erhalten als der aufrufende Schlüssel selbst besitzt. | Aktiviere unter Models → API-Schlüssel die passende Verwaltungsberechtigung („Tag-Verwaltung erlauben (/v1/tags)“ bzw. „Shield-Richtlinie per API verwalten“) und ändere Richtlinien nur im Rahmen der eigenen Schlüssel-Einschränkungen. |
model_not_allowed_for_tag | Das Modell gehört nicht zu den erlaubten Modellen eines in X-Noirdoc-Tags genannten Tags. | Wähle ein Modell aus GET /v1/models (mit demselben Header X-Noirdoc-Tags) oder erweitere die erlaubten Modelle des Tags unter Models → Tags. |
provider_not_allowed_for_tag | Die Einschränkungen eines in X-Noirdoc-Tags genannten Tags (Anbieter, Datenresidenz, CLOUD Act, § 203) schließen jeden Anbieter dieses Modells aus. | Wähle ein Modell aus GET /v1/models (mit demselben Header X-Noirdoc-Tags) oder lockere die Einschränkungen des Tags unter Models → Tags. |
| 404 Nicht gefunden | ||
unsupported_endpoint | Das Gateway kennt diesen Pfad nicht. | Verwende einen Endpunkt aus der Referenz und prüfe Schreibweise und Präfix /v1/. |
object_not_found | Das Objekt (Datei, Skill oder gespeicherte Antwort) existiert nicht oder gehört nicht deiner Organisation. | Prüfe die ID. Verwende nur IDs, die deine Organisation über das Gateway angelegt hat. |
model_not_available | Die Modell-ID ist für die Organisation nicht verfügbar. | Prüfe die Modell-ID mit GET /v1/models. |
http_error | Eine Anfrage scheitert mit einem allgemeinen HTTP-Fehler, für den das Gateway keinen eigenen Code vergibt. Der Statuscode folgt dem Fehler: 404 bei einem unbekannten Pfad, 405 bei einer falschen Methode und 503 mit Retry-After: 5, wenn ein Endpunkt im Standalone-Betrieb nicht verfügbar ist. | Lies message und prüfe Methode und Pfad der Anfrage. |
| 405 Methode nicht erlaubt | ||
method_not_allowed | Der Endpunkt nimmt nur POST an. | Sende die Anfrage mit POST. |
| 409 Konflikt | ||
tag_already_exists | Ein Tag mit diesem Namen existiert in der Organisation bereits. | Wähle einen anderen Tag-Namen oder aktualisiere das bestehende Tag mit PUT /v1/tags/{name} bzw. PATCH /v1/tags/{name}. |
tag_has_spend_history | Für das Tag wurden bereits Kosten verbucht; es lässt sich deshalb nicht endgültig löschen. | Belasse das Tag im Status „Inaktiv“, damit Zähler und Abrechnungshistorie erhalten bleiben. |
| 413 Anfrage zu groß | ||
request_too_large | Der Body überschreitet das Größenlimit des Endpunkts. | Verkleinere oder teile den Body, etwa die Audiodatei oder eingebettete Dateien. Die Werte stehen unter Grenzen. |
shield_input_too_large | Der zu prüfende Text der Anfrage überschreitet das Limit des Shield-Dienstes von 4 MiB kodiertem Text in einem Aufruf. | Teile große Eingaben oder eingebettete Textdateien auf mehrere kleinere Anfragen auf. |
masking_input_too_large | Ein einzelner Textabschnitt in einer Anfrage mit klassischer Maskierung (Übergangsbetrieb bis 30.11.2026) überschreitet das Zeichenlimit des Detektors. | Teile den Text in kleinere Abschnitte auf oder stelle unter Models → Shield auf Noirdoc Shield um. |
| 422 Nicht verarbeitbar | ||
shield_uninspectable_content | Die Shield-Richtlinie steht auf enforced, und die Anfrage enthält Inhalte, die Shield nicht als Text prüfen kann (binary_document wie PDF oder Office, media_not_inspectable wie Bilder, Audio oder Video, file_reference per ID oder URL, file_too_large ab 4 MiB, file_not_decodable oder unrecognised_content). Das Gateway hat die Anfrage nicht weitergeleitet. | Extrahiere den Text vorab und sende ihn als Nachrichtentext oder UTF-8-Textdatei unter 4 MiB inline, oder wechsle unter Models → Shield von enforced auf default_on. |
shield_policy_invalid | Die übergebene Shield-Richtlinie ist widersprüchlich, etwa enforced mit allen fünf Schutzfiltern auf off oder eine Mischung aus rules/custom_patterns und flachen Regelschlüsseln. | Aktiviere bei enforced mindestens einen Schutzfilter und übergib Regelaktionen gesammelt im Objekt rules. |
shield_config_invalid | Die gespeicherte Shield-Konfiguration der Organisation ist ungültig (zum Beispiel enforced ohne aktiven Schutzfilter oder ein nicht kompilierbares Muster); das Gateway hat die Anfrage nicht weitergeleitet. | Prüfe und speichere die Schutzfilter und eigenen Sperrbegriffe unter Models → Shield oder über /v1/shield/policy neu. |
file_unprocessable | Eine Datei ließ sich in der klassischen Dateianalyse (Übergangsbetrieb bis 30.11.2026) nicht verarbeiten: Die Datei ist zu groß, nicht lesbar oder hat ein Format ohne Analyse. Das Gateway hat die Anfrage nicht weitergeleitet. | Speichere die Datei neu oder in einem anderen Format (etwa PDF, DOCX oder XLSX), verkleinere sie oder extrahiere den Text vorab für Noirdoc Shield. |
| 429 Rate Limit oder Anbieter ausgelastet | ||
starter_rate_limit_exceeded | Die Organisation nutzt noch ausschließlich das Startguthaben und hat die Grenze von 5 Anfragen je Minute oder 25 Anfragen je Tag (UTC) für verwaltete Anbieter erreicht. Die Antwort enthält Retry-After mit der Wartezeit in Sekunden. | Lade unter Abrechnung → Aufladen Guthaben auf, um die Grenze sofort aufzuheben, oder warte die Sekunden aus Retry-After ab. |
resource_exhausted | Der Anbieter hat Kapazitätsprobleme oder ein erschöpftes Guthaben gemeldet (Statuscode 429 oder 402), auch nach Failover über bis zu drei Anbieter. Die Antwort enthält Retry-After mit der Wartezeit in Sekunden. | Warte die Sekunden aus Retry-After ab und sende die Anfrage erneut. Die OpenAI- und Anthropic-SDKs tun das selbst. |
| 500 Interner Fehler | ||
internal_error | Im Gateway ist ein unerwarteter Fehler aufgetreten. | Sende die Anfrage erneut. Bleibt der Fehler bestehen, nenne dem Support die Anfrage-ID aus message oder x-request-id. |
detection_error | Die Erkennung personenbezogener Daten in der klassischen Maskierung (Übergangsbetrieb bis 30.11.2026) ist fehlgeschlagen; das Gateway hat die Anfrage nicht weitergeleitet. | Sende die Anfrage erneut. Bleibt der Fehler bestehen, wende dich an den Support oder stelle unter Models → Shield auf Noirdoc Shield um. |
file_analysis_error | Reserviert für Fehler der Dateianalyse. Das Gateway sendet diesen Code derzeit nicht. | Sende die Anfrage erneut. |
| 502 Anbieterfehler | ||
provider_not_configured | Für diese Anfrage ist in der Organisation kein passender Anbieter eingerichtet. | Verbinde unter Models → Provider einen Anbieter für dieses API-Format. |
provider_misconfigured | Die Konfiguration des gewählten Anbieters ist ungültig, zum Beispiel eine nicht erlaubte Basis-URL. | Prüfe Basis-URL und Einstellungen des Anbieters unter Models → Provider. Betrifft es einen von Noirdoc verwalteten Anbieter, wende dich an den Support. |
provider_unreachable | Das Gateway konnte keine Verbindung zum Anbieter herstellen, oder die Verbindung ist abgebrochen. | Sende die Anfrage nach einer kurzen Wartezeit erneut. |
provider_error | Der Anbieter hat mit einem Fehler geantwortet (Statuscode 5xx außer 503 und 529, oder 401 und 403 auf Routen mit einem von Noirdoc verwalteten Anbieter), den die Anfrage nicht verursacht hat. Das Gateway ersetzt die Meldung des Anbieters durch einen festen Text. Auf Routen mit eigenem Anbieter-Schlüssel meldet es 401 und 403 als provider_rejected_request. | Sende die Anfrage erneut. Bleibt der Fehler bestehen, nenne dem Support die Anfrage-ID aus message oder x-request-id. |
stream_interrupted | Der Stream des Anbieters ist nach dem Beginn der Antwort abgebrochen oder hat einen Fehler gemeldet. Der Fehler steht im Stream selbst, weil der Statuscode 200 dann bereits gesendet ist. stream_interrupted trägt kein retry_after; nur Fehler im Stream, die einem HTTP-Fehler mit Wartezeit entsprechen, tragen es. | Verwirf die unvollständige Antwort und sende die Anfrage erneut. |
| 503 Vorübergehend nicht verfügbar | ||
capacity_exhausted | Alle Anbieter des Modells waren an ihrer Kapazitätsgrenze oder nach einem 429 pausiert, auch nach einer Wartezeit von bis zu 10 Sekunden. Die Antwort enthält Retry-After mit den Sekunden, bis voraussichtlich ein Anbieter wieder frei ist, höchstens 60, oder 5 Sekunden, wenn das nicht bekannt ist. | Warte die Sekunden aus Retry-After ab und sende die Anfrage erneut. Die OpenAI- und Anthropic-SDKs tun das selbst. |
provider_overloaded | Der Anbieter hat Überlast gemeldet (Statuscode 503 oder 529), auch nach Failover über bis zu drei Anbieter. Der Statuscode ist 503 bei OpenAI-Endpunkten und 529 bei /v1/messages und /v1/skills. Die Antwort enthält Retry-After mit dem Wert des Anbieters zwischen 1 und 60 Sekunden, sonst 5 Sekunden. | Warte die Sekunden aus Retry-After ab und sende die Anfrage erneut. Die OpenAI- und Anthropic-SDKs tun das selbst. |
service_overloaded | Das Gateway ist vorübergehend ausgelastet. Die Antwort enthält Retry-After mit 5 Sekunden. | Warte die Sekunden aus Retry-After ab und sende die Anfrage erneut. |
forwarding_pool_exhausted | Alle Verbindungen des Gateways zu den Anbietern sind belegt. Das ist eine Grenze des Gateways, nicht die eines Anbieters. Die Antwort enthält Retry-After mit 5 Sekunden. | Warte die Sekunden aus Retry-After ab und sende die Anfrage erneut. Die OpenAI- und Anthropic-SDKs tun das selbst. |
provider_auth_unavailable | Die Zugangsdaten des Gateways für den Anbieter sind gerade nicht verfügbar. Die Antwort enthält Retry-After mit 5 Sekunden. | Sende die Anfrage später erneut. |
ownership_check_unavailable | Das Gateway konnte gerade nicht prüfen, ob das Objekt deiner Organisation gehört, und hat die Anfrage abgelehnt. Die Antwort enthält Retry-After mit 5 Sekunden. | Sende die Anfrage erneut. |
shield_unavailable | Der Noirdoc-Shield-Prüfdienst ist vorübergehend nicht erreichbar; das Gateway leitet eine zu prüfende Anfrage niemals ungeprüft weiter (Fail-closed). Die Antwort enthält Retry-After mit 5 Sekunden. | Warte die Sekunden aus Retry-After ab und sende die Anfrage erneut. Die OpenAI- und Anthropic-SDKs tun das selbst. |
masking_unavailable | Der Detektor der klassischen Maskierung (Übergangsbetrieb bis 30.11.2026) ist vorübergehend nicht erreichbar; das Gateway hat die Anfrage nicht weitergeleitet. Die Antwort enthält Retry-After mit 10 Sekunden. | Warte die Sekunden aus Retry-After ab und sende die Anfrage erneut. |
gateway_restarting | Das Gateway wurde neu gestartet (Deployment), während der Stream noch auf die Antwort des Anbieters wartete. Der Fehler steht im laufenden Stream, weil der Statuscode 200 dann bereits gesendet ist. Das Fehlerobjekt enthält retry_after mit 5 Sekunden. | Warte die Sekunden aus retry_after ab und sende die Anfrage erneut. |
| 504 Zeitüberschreitung | ||
provider_timeout | Der Anbieter hat nicht innerhalb der Wartezeit des Gateways geantwortet. Die Antwort enthält Retry-After mit 10 Sekunden. | Warte die Sekunden aus Retry-After ab und sende die Anfrage erneut. |