Chat & Responses.
Erzeugt Modellantworten im Format der OpenAI Chat Completions und Responses API, prüft Eingaben mit Noirdoc Shield und routet über europäische Anbieter.
Chat Completions.
Nimmt Anfragen im Format der OpenAI Chat Completions API entgegen (https://api.noirdoc.de/v1) und routet sie über europäische Anbieter.
POST https://api.noirdoc.de/v1/chat/completions
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.noirdoc.de/v1",
api_key=os.environ["NOIRDOC_API_KEY"],
)
res = client.chat.completions.create(
model="qwen3.8-27b",
messages=[
{"role": "user", "content": "Prüfe Absatz 4 auf Fristen."}
],
extra_headers={"X-Noirdoc-Shield": "on"},
)
print(res.choices[0].message.content)import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.noirdoc.de/v1",
apiKey: process.env.NOIRDOC_API_KEY,
});
const res = await client.chat.completions.create(
{
model: "qwen3.8-27b",
messages: [{ role: "user", content: "Prüfe Absatz 4 auf Fristen." }],
},
{ headers: { "X-Noirdoc-Shield": "on" } },
);
console.log(res.choices[0]?.message.content);curl https://api.noirdoc.de/v1/chat/completions \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Noirdoc-Shield: on" \
-d '{
"model": "qwen3.8-27b",
"messages": [
{"role": "user", "content": "Prüfe Absatz 4 auf Fristen."}
]
}'// 200 OK · X-Noirdoc-Provider: ionos · X-Noirdoc-Shield: redacted=0
{
"id": "chatcmpl-8e21a9",
"object": "chat.completion",
"model": "qwen3.8-27b",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Absatz 4 setzt drei Monate Kündigungsfrist.",
},
"finish_reason": "stop",
},
],
"usage": {
"prompt_tokens": 18,
"completion_tokens": 24,
"total_tokens": 42,
},
}Alle Modell-IDs stehen im Modellkatalog und live unter
GET /v1/models.
Standardfelder wie messages, tools, tool_choice, response_format und stream verhalten sich wie in der OpenAI-Spezifikation. Nur diese Punkte regelt das Gateway anders:
| Bereich | Verhalten bei Noirdoc |
|---|---|
model | Öffentliche Modell-ID der Familie chat aus GET /v1/models (z. B. qwen3.8-27b). Alle Modelle im OpenAI-Format sowie Gemini-Modelle über Google Vertex laufen auf diesem Endpunkt; verwaltete claude-*-Modelle beantwortet das Gateway mit 400 wrong_endpoint_for_model (nutze dafür POST /v1/messages). Im Startguthaben sind nur freigegebene Modelle aufrufbar, andere verwaltete Modelle ergeben 403 starter_model_not_allowed (Guthaben). Im Antwortfeld model setzt das Gateway wieder die von dir gesendete ID ein. |
| Anbieter & Failover | X-Noirdoc-Provider nennt den ausführenden Anbieter, auch bei Anbieterfehlern. Antwortet ein Anbieter vor dem ersten Byte mit 429, 5xx oder Netzwerkfehler, versucht das Gateway bis zu drei Anbieter derselben Art (verwaltete Anbieter und BYOK werden nie gemischt, siehe Routing). |
| SSE Keep-Alive & Usage | Bei "stream": true sendet das Gateway nach 15 Sekunden Wartezeit Status 200 und alle 15 Sekunden die Kommentarzeile : ping (Gesamtlimit 600 s statt 120 s). Wurde 200 vorab gesendet, steht der Anbieter als : provider=<slug> vor dem ersten Daten-Event statt im HTTP-Header. Für die Abrechnung aktiviert das Gateway intern stream_options.include_usage und entfernt das zusätzliche Usage-Chunk wieder, sofern du include_usage: true nicht selbst angefordert hast (Streaming). |
| Noirdoc Shield | Ersetzt sensible Werte in messages bei aktiver Prüfung direkt vor Ort durch feste Platzhalter ([PERSON], [IBAN], …) ohne System-Prompt-Zusatz oder Chunk-Pufferung; block-Regeln brechen mit 403 shield_violation ab (Geprüfte Felder). Die umkehrbare Maskierung (<<PERSON_1>>) gilt nur noch für Bestandsorganisationen bis zum 30.11.2026 (Klassische Maskierung). |
Dateien, Bilder & file_id | Teile vom Typ image_url, file und input_audio setzen voraus, dass unter Models → Shield die Option Dateianhänge und Bilder in Anfragen erlauben aktiv ist (sonst 403 file_content_not_allowed). Eingebettete UTF-8-Textdateien unter 4 MiB prüft Shield direkt; Binärdateien, Bilder und Audio ergeben X-Noirdoc-Shield: partial; redacted=<n> oder unter enforced 422 shield_uninspectable_content (Dateien). Auf verwalteten Anbietern muss eine file_id deiner Organisation gehören (sonst 404 object_not_found). |
| Speicherung & Unterrouten | Auf verwalteten Anbietern lehnt das Gateway "store": true mit 403 stored_responses_disabled ab, solange Responses-API Speicherung beim Anbieter erlauben unter Models → Shield ausgeschaltet ist. Die Unterrouten GET /v1/chat/completions, GET|DELETE /v1/chat/completions/{id} und GET /v1/chat/completions/{id}/messages stehen nur mit eigenem OpenAI-Anbieter-Schlüssel (BYOK) bereit (sonst 403 endpoint_not_available_on_platform, ohne konfigurierten Anbieter 502 provider_not_configured). Gespeicherte Einträge enthalten die einseitigen [PERSON]-Platzhalter. Andere Pfade unter /v1/chat/completions/ liefern 404 unsupported_endpoint. |
| Entfernte Header | Vor der Weiterleitung entfernt das Gateway deinen API-Schlüssel sowie X-Noirdoc-Shield und X-Noirdoc-Mask. |
| Status | Code | Bedeutung |
|---|---|---|
| 400 | invalid_request_path | Der Pfad enthält ein Punkt-Segment (. oder ..), ein %, einen Backslash oder ein Steuerzeichen. |
| 400 | model_required | Die Anfrage nennt kein Modell (model im Body, bei /v1/audio/transcriptions im Formularfeld). |
| 400 | wrong_endpoint_for_model | Das Modell gehört zu einer anderen Endpunkt-Familie oder einem anderen API-Format als der aufgerufene Endpunkt. |
| 400 | invalid_request_body | Der Body ist kein JSON-Objekt oder nicht in UTF-8 kodiert. |
| 400 | 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. |
| 400 | 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. |
| 400 | 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}$. |
| 401 | invalid_api_key | Der Schlüssel fehlt, ist ungültig oder deaktiviert, oder die Organisation ist nicht aktiv. |
| 402 | 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). |
| 402 | 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. |
| 402 | 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. |
| 403 | endpoint_not_available_on_platform | Der Aufruf würde Daten aus dem gemeinsamen Konto eines von Noirdoc verwalteten Anbieters lesen und ist dort gesperrt. |
| 403 | 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. |
| 403 | 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. |
| 403 | model_not_allowed_for_key | Das Modell gehört nicht zu den erlaubten Modellen dieses Schlüssels. |
| 403 | provider_not_allowed_for_tenant | Die Organisation gilt als Berufsgeheimnisträger (§ 203 StGB); das schließt jeden Anbieter aus, der dieses Modell anbietet. |
| 403 | provider_not_allowed_for_key | Die Einschränkungen des Schlüssels (Anbieter, Datenresidenz, CLOUD Act, § 203) schließen jeden Anbieter dieses Modells aus. |
| 403 | starter_model_not_allowed | Die Organisation nutzt noch ausschließlich das Startguthaben, und das Modell bzw. sein verwalteter Anbieter ist im Startguthaben nicht freigegeben. |
| 403 | 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). |
| 403 | file_content_not_allowed | Die Anfrage enthält Dateien, Bilder oder Audio, und die Organisation lässt keine Dateiinhalte zu. |
| 403 | 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. |
| 403 | model_not_billable | Für das Modell ist kein vollständiger Preis hinterlegt, deshalb lässt es sich mit Guthaben nicht nutzen. |
| 403 | 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. |
| 403 | 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. |
| 403 | tag_disabled | Ein in X-Noirdoc-Tags genanntes Tag ist deaktiviert. |
| 403 | tag_limit_exceeded | Die Organisation hat die Obergrenze von 1.000 Request-Tags erreicht. |
| 403 | model_not_allowed_for_tag | Das Modell gehört nicht zu den erlaubten Modellen eines in X-Noirdoc-Tags genannten Tags. |
| 403 | 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. |
| 404 | object_not_found | Das Objekt (Datei, Skill oder gespeicherte Antwort) existiert nicht oder gehört nicht deiner Organisation. |
| 404 | model_not_available | Die Modell-ID ist für die Organisation nicht verfügbar. |
| 413 | request_too_large | Der Body überschreitet das Größenlimit des Endpunkts. |
| 413 | 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. |
| 413 | masking_input_too_large | Ein einzelner Textabschnitt in einer Anfrage mit klassischer Maskierung (Übergangsbetrieb bis 30.11.2026) überschreitet das Zeichenlimit des Detektors. |
| 422 | 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. |
| 422 | 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. |
| 422 | 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. |
| 429 | 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. |
| 429 | 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. |
| 500 | internal_error | Im Gateway ist ein unerwarteter Fehler aufgetreten. |
| 500 | detection_error | Die Erkennung personenbezogener Daten in der klassischen Maskierung (Übergangsbetrieb bis 30.11.2026) ist fehlgeschlagen; das Gateway hat die Anfrage nicht weitergeleitet. |
| 502 | provider_not_configured | Für diese Anfrage ist in der Organisation kein passender Anbieter eingerichtet. |
| 502 | provider_misconfigured | Die Konfiguration des gewählten Anbieters ist ungültig, zum Beispiel eine nicht erlaubte Basis-URL. |
| 502 | provider_unreachable | Das Gateway konnte keine Verbindung zum Anbieter herstellen, oder die Verbindung ist abgebrochen. |
| 502 | 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. |
| 502 | 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. |
| 503 | 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. |
| 503 | 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. |
| 503 | service_overloaded | Das Gateway ist vorübergehend ausgelastet. Die Antwort enthält Retry-After mit 5 Sekunden. |
| 503 | 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. |
| 503 | 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. |
| 503 | 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. |
| 503 | 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. |
| 503 | 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. |
| 503 | 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. |
| 504 | provider_timeout | Der Anbieter hat nicht innerhalb der Wartezeit des Gateways geantwortet. Die Antwort enthält Retry-After mit 10 Sekunden. |
Responses.
Nimmt Anfragen im Format der OpenAI Responses API entgegen und leitet sie an Anbieter im OpenAI-Format weiter, die diesen Endpunkt unterstützen (endpoint_family: "chat" in GET /v1/models; lehnt ein Anbieter das Format ab, antwortet das Gateway mit provider_rejected_request).
POST https://api.noirdoc.de/v1/responses
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.noirdoc.de/v1",
api_key=os.environ["NOIRDOC_API_KEY"],
)
res = client.responses.create(
model="qwen3.8-27b",
instructions="Antworte in höchstens drei Sätzen.",
input="Welche Fristen nennt Klausel 8?",
extra_headers={"X-Noirdoc-Shield": "on"},
)
print(res.output_text)import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.noirdoc.de/v1",
apiKey: process.env.NOIRDOC_API_KEY,
});
const res = await client.responses.create(
{
model: "qwen3.8-27b",
instructions: "Antworte in höchstens drei Sätzen.",
input: "Welche Fristen nennt Klausel 8?",
},
{ headers: { "X-Noirdoc-Shield": "on" } },
);
console.log(res.output_text);curl https://api.noirdoc.de/v1/responses \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Noirdoc-Shield: on" \
-d '{
"model": "qwen3.8-27b",
"instructions": "Antworte in höchstens drei Sätzen.",
"input": "Welche Fristen nennt Klausel 8?"
}'// 200 OK · X-Noirdoc-Provider: azure
{
"id": "resp_4f92c1",
"object": "response",
"model": "qwen3.8-27b",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "Klausel 8 legt eine Prüffrist von 14 Tagen fest.",
},
],
},
],
"usage": {
"input_tokens": 23,
"output_tokens": 16,
"total_tokens": 39,
},
}Im Unterschied zu OpenAI arbeitet /v1/responses bei Noirdoc standardmäßig zustandslos ohne Speicherung beim Anbieter:
| Bereich | Verhalten bei Noirdoc |
|---|---|
Zustandsloser Standard (store) | Auf verwalteten Anbietern setzt das Gateway store standardmäßig auf false, solange unter Models → Shield die Option Responses-API Speicherung beim Anbieter erlauben aus ist (Standard für neue Organisationen). Solange sie ausgeschaltet ist, beantwortet das Gateway "store": true, previous_response_id und Aufrufe auf /v1/responses/{id} mit 403 stored_responses_disabled. Übergib den bisherigen Verlauf direkt in input; Reasoning-Modelle bleiben über include: ["reasoning.encrypted_content"] zustandslos nutzbar. Mit eigenem Anbieter-Schlüssel (BYOK) entfällt diese Sperre. |
| Gespeicherte Objekt-Verweise | Auf verwalteten Anbietern lehnt das Gateway conversation, prompt.id, input[]-Einträge vom Typ item_reference oder nur mit id sowie tools[].vector_store_ids mit 403 reference_not_available_on_platform ab. previous_response_id, file_id und Container müssen über deine Organisation entstanden sein (sonst 404 object_not_found). Unter Shield benötigt previous_response_id keinen Zuordnungsspeicher, da [PERSON]-Platzhalter einseitig sind. Auf BYOK-Routen entfallen diese Prüfungen. |
| Noirdoc Shield & Anhänge | Prüft instructions und input vor Ort ([PERSON], [IBAN], … oder 403 shield_violation). Für input_image und input_file gelten dieselben Schalter- und 4-MiB-UTF-8-Regeln wie bei Chat Completions (Dateien). |
| Unterrouten | POST /v1/responses/input_tokens zählt Eingabe-Tokens für model, überspringt Shield und kostet 0 € (liefert bei erschöpftem Guthaben oder Schlüsselbudget auf verwalteten Anbietern dennoch 402). POST /v1/responses/compact verlangt model, durchläuft bei aktivem Shield die Prüfung und wird nach Tokens abgerechnet. GET|DELETE /v1/responses/{id}, POST /v1/responses/{id}/cancel und GET /v1/responses/{id}/input_items tragen kein model und gehen an den ältesten aktiven OpenAI-Anbieter deiner Organisation (BYOK vorrangig; auf verwalteten Anbietern nur bei aktivierter Speicherung und eigenen IDs, sonst 404 object_not_found). Andere Pfade unter /v1/responses/ ergeben 404 unsupported_endpoint. |
| Streaming & Startguthaben | 15-Sekunden-: ping-Keep-Alive, : provider=<slug> und die Prüfung auf starter_model_not_allowed im Startguthaben entsprechen /v1/chat/completions. Bricht ein Stream ab, sendet das Gateway ein error-Event gefolgt von data: [DONE] — prüfe im OpenAI-Python-SDK event.type == "error" in deiner Schleife (Streaming). |
| Status | Code | Bedeutung |
|---|---|---|
| 400 | invalid_request_path | Der Pfad enthält ein Punkt-Segment (. oder ..), ein %, einen Backslash oder ein Steuerzeichen. |
| 400 | model_required | Die Anfrage nennt kein Modell (model im Body, bei /v1/audio/transcriptions im Formularfeld). |
| 400 | wrong_endpoint_for_model | Das Modell gehört zu einer anderen Endpunkt-Familie oder einem anderen API-Format als der aufgerufene Endpunkt. |
| 400 | invalid_request_body | Der Body ist kein JSON-Objekt oder nicht in UTF-8 kodiert. |
| 400 | 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. |
| 400 | 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. |
| 400 | 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}$. |
| 401 | invalid_api_key | Der Schlüssel fehlt, ist ungültig oder deaktiviert, oder die Organisation ist nicht aktiv. |
| 402 | 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). |
| 402 | 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. |
| 402 | 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. |
| 403 | endpoint_not_available_on_platform | Der Aufruf würde Daten aus dem gemeinsamen Konto eines von Noirdoc verwalteten Anbieters lesen und ist dort gesperrt. |
| 403 | 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. |
| 403 | 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. |
| 403 | model_not_allowed_for_key | Das Modell gehört nicht zu den erlaubten Modellen dieses Schlüssels. |
| 403 | provider_not_allowed_for_tenant | Die Organisation gilt als Berufsgeheimnisträger (§ 203 StGB); das schließt jeden Anbieter aus, der dieses Modell anbietet. |
| 403 | provider_not_allowed_for_key | Die Einschränkungen des Schlüssels (Anbieter, Datenresidenz, CLOUD Act, § 203) schließen jeden Anbieter dieses Modells aus. |
| 403 | starter_model_not_allowed | Die Organisation nutzt noch ausschließlich das Startguthaben, und das Modell bzw. sein verwalteter Anbieter ist im Startguthaben nicht freigegeben. |
| 403 | 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). |
| 403 | file_content_not_allowed | Die Anfrage enthält Dateien, Bilder oder Audio, und die Organisation lässt keine Dateiinhalte zu. |
| 403 | 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. |
| 403 | model_not_billable | Für das Modell ist kein vollständiger Preis hinterlegt, deshalb lässt es sich mit Guthaben nicht nutzen. |
| 403 | 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. |
| 403 | 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. |
| 403 | tag_disabled | Ein in X-Noirdoc-Tags genanntes Tag ist deaktiviert. |
| 403 | tag_limit_exceeded | Die Organisation hat die Obergrenze von 1.000 Request-Tags erreicht. |
| 403 | model_not_allowed_for_tag | Das Modell gehört nicht zu den erlaubten Modellen eines in X-Noirdoc-Tags genannten Tags. |
| 403 | 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. |
| 404 | object_not_found | Das Objekt (Datei, Skill oder gespeicherte Antwort) existiert nicht oder gehört nicht deiner Organisation. |
| 404 | model_not_available | Die Modell-ID ist für die Organisation nicht verfügbar. |
| 413 | request_too_large | Der Body überschreitet das Größenlimit des Endpunkts. |
| 413 | 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. |
| 413 | masking_input_too_large | Ein einzelner Textabschnitt in einer Anfrage mit klassischer Maskierung (Übergangsbetrieb bis 30.11.2026) überschreitet das Zeichenlimit des Detektors. |
| 422 | 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. |
| 422 | 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. |
| 422 | 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. |
| 429 | 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. |
| 429 | 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. |
| 500 | internal_error | Im Gateway ist ein unerwarteter Fehler aufgetreten. |
| 500 | detection_error | Die Erkennung personenbezogener Daten in der klassischen Maskierung (Übergangsbetrieb bis 30.11.2026) ist fehlgeschlagen; das Gateway hat die Anfrage nicht weitergeleitet. |
| 502 | provider_not_configured | Für diese Anfrage ist in der Organisation kein passender Anbieter eingerichtet. |
| 502 | provider_misconfigured | Die Konfiguration des gewählten Anbieters ist ungültig, zum Beispiel eine nicht erlaubte Basis-URL. |
| 502 | provider_unreachable | Das Gateway konnte keine Verbindung zum Anbieter herstellen, oder die Verbindung ist abgebrochen. |
| 502 | 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. |
| 502 | 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. |
| 503 | 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. |
| 503 | 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. |
| 503 | service_overloaded | Das Gateway ist vorübergehend ausgelastet. Die Antwort enthält Retry-After mit 5 Sekunden. |
| 503 | 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. |
| 503 | 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. |
| 503 | 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. |
| 503 | 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. |
| 503 | 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. |
| 503 | 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. |
| 504 | provider_timeout | Der Anbieter hat nicht innerhalb der Wartezeit des Gateways geantwortet. Die Antwort enthält Retry-After mit 10 Sekunden. |