Audio, Bilder & Dateien.
Transkribiert Audio, erzeugt Sprachausgabe und Bilder, prüft eingebettete Textdateien mit Shield und leitet /v1/files sowie /v1/skills durch.
Audio.
Keine Prüfung durch Noirdoc Shield:
/v1/audio/*und/v1/images/generationsprüfen weder Audiodateien noch Eingabetexte (für eine Vorab-Prüfung von Text stehtPOST /v1/shield/inspectbereit). Unter der Richtlinieenforcedoder mitX-Noirdoc-Mask: on(auf/v1/images/generationsauch mitX-Noirdoc-Shield: on) lehnt das Gateway Anfragen mit 403masking_not_supported_for_endpointab. Mitdefault_onoderdefault_offohne Prüf-Header leitet es sie ungeprüft weiter.
POST /v1/audio/transcriptions nimmt multipart/form-data im Format der OpenAI Audio API entgegen (endpoint_family: "stt" in GET /v1/models).
POST https://api.noirdoc.de/v1/audio/transcriptions
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.noirdoc.de/v1",
api_key=os.environ["NOIRDOC_API_KEY"],
)
with open("diktat.mp3", "rb") as audio:
transcript = client.audio.transcriptions.create(
model="whisper",
file=audio,
)
print(transcript.text)import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.noirdoc.de/v1",
apiKey: process.env.NOIRDOC_API_KEY,
});
const transcript = await client.audio.transcriptions.create({
model: "whisper",
file: fs.createReadStream("diktat.mp3"),
});
console.log(transcript.text);curl https://api.noirdoc.de/v1/audio/transcriptions \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-F model="whisper" \
-F file="@diktat.mp3"// 200 OK · X-Noirdoc-Provider: azure
{
"text": "Die Frist zur Stellungnahme endet am kommenden Freitag.",
}POST /v1/audio/speech nimmt JSON im Format der OpenAI Audio API entgegen (endpoint_family: "tts") und liefert die binären Audiodaten mit dem Content-Type des Anbieters zurück.
POST https://api.noirdoc.de/v1/audio/speech
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.noirdoc.de/v1",
api_key=os.environ["NOIRDOC_API_KEY"],
)
speech = client.audio.speech.create(
model="tts",
voice="alloy",
response_format="mp3",
input="Der Termin findet am Dienstag um 10 Uhr statt.",
)
speech.write_to_file("termin.mp3")import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.noirdoc.de/v1",
apiKey: process.env.NOIRDOC_API_KEY,
});
const speech = await client.audio.speech.create({
model: "tts",
voice: "alloy",
response_format: "mp3",
input: "Der Termin findet am Dienstag um 10 Uhr statt.",
});
fs.writeFileSync("termin.mp3", Buffer.from(await speech.arrayBuffer()));curl https://api.noirdoc.de/v1/audio/speech \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "tts",
"voice": "alloy",
"response_format": "mp3",
"input": "Der Termin findet am Dienstag um 10 Uhr statt."
}' \
--output termin.mp3HTTP/1.1 200 OK
content-type: audio/mpeg
x-noirdoc-provider: azure
<MP3-Audiodaten>| Bereich | Verhalten bei Noirdoc |
|---|---|
Transkription (stt) | Multipart-Body höchstens 26 MB (26 × 1024 × 1024 Byte inklusive Formularfeldern, sonst 413 request_too_large). model, stream und response_format dürfen je höchstens einmal vorkommen (sonst 400 invalid_multipart_body). Erfordert aktivierte Option Dateianhänge und Bilder in Anfragen erlauben unter Models → Shield (sonst 403 file_content_not_allowed). |
response_format & Abrechnung (stt) | Abrechnung nach Audiodauer. Bei json, text oder ohne Angabe fragt das Gateway intern verbose_json beim Anbieter an, liest die Dauer aus und wandelt in das angeforderte Format zurück (meldet der Anbieter keine Dauer, bleibt verbose_json erhalten). verbose_json, srt und vtt laufen unverändert durch. |
Sprachausgabe (tts) | input erforderlich (1 bis 4.096 Zeichen), voice als nicht leerer String erforderlich (sonst 400 invalid_tts_request). Abrechnung nach Zeichenanzahl in input. |
| Streaming, Methoden & Startguthaben | Nur POST (sonst 405 method_not_allowed); andere Pfade unter /v1/audio/ liefern 404 unsupported_endpoint. stream (true, 1, yes, on) bzw. stream_format ergeben 400 streaming_not_supported_for_endpoint. Nicht im Startguthaben freigegebene verwaltete Modelle liefern 403 starter_model_not_allowed. X-Noirdoc-Provider nennt den Anbieter. |
| Status | Code | Bedeutung |
|---|---|---|
| 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 | streaming_not_supported_for_endpoint | Die Anfrage verlangt Streaming, der Endpunkt unterstützt es aber nicht. |
| 400 | invalid_request_body | Der Body ist kein JSON-Objekt oder nicht in UTF-8 kodiert. |
| 400 | invalid_tts_request | input oder voice fehlt oder ist leer, oder input ist zu lang. |
| 400 | invalid_multipart_body | Der Body ist kein gültiges multipart/form-data, oder model, stream bzw. response_format kommt mehrfach vor. |
| 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 | 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. |
| 403 | file_content_not_allowed | Die Anfrage enthält Dateien, Bilder oder Audio, und die Organisation lässt keine Dateiinhalte zu. |
| 405 | method_not_allowed | Der Endpunkt nimmt nur POST an. |
| 413 | request_too_large | Der Body überschreitet das Größenlimit des Endpunkts. |
Bilder.
Erzeugt Bilder aus einem Text-Prompt im Format der OpenAI Images API (endpoint_family: "image_gen" in GET /v1/models) und gibt Base64-kodierte Bilddaten in data[].b64_json zurück.
POST https://api.noirdoc.de/v1/images/generations
import base64
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.noirdoc.de/v1",
api_key=os.environ["NOIRDOC_API_KEY"],
)
img = client.images.generate(
model="black-forest-labs/FLUX.1-schnell",
prompt="Ein Leuchtturm an der Nordsee bei Sonnenaufgang",
size="1024x1024",
n=1,
)
raw = base64.b64decode(img.data[0].b64_json or "")
with open("leuchtturm.png", "wb") as f:
f.write(raw)import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.noirdoc.de/v1",
apiKey: process.env.NOIRDOC_API_KEY,
});
const img = await client.images.generate({
model: "black-forest-labs/FLUX.1-schnell",
prompt: "Ein Leuchtturm an der Nordsee bei Sonnenaufgang",
size: "1024x1024",
n: 1,
});
const png = Buffer.from(img.data?.[0]?.b64_json ?? "", "base64");
fs.writeFileSync("leuchtturm.png", png);curl https://api.noirdoc.de/v1/images/generations \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "black-forest-labs/FLUX.1-schnell",
"prompt": "Ein Leuchtturm an der Nordsee bei Sonnenaufgang",
"size": "1024x1024",
"n": 1
}'// 200 OK · X-Noirdoc-Provider: ionos
{
"created": 1763180400,
"data": [
{
"b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU...",
},
],
}| Feld / Bereich | Regel bei Noirdoc |
|---|---|
prompt & Shield | Nicht leerer String (sonst 400 invalid_image_request). Keine Shield-Prüfung: enforced, X-Noirdoc-Shield: on oder X-Noirdoc-Mask: on brechen mit 403 masking_not_supported_for_endpoint ab. |
n & size | n als ganze Zahl von 1 bis 10 (Standard 1). size als BREITExHÖHE mit je 1 bis 2048 Pixeln (ohne Angabe 1024x1024; "auto" lehnt das Gateway mit 400 invalid_image_request ab). Engere Modellgrenzen des Anbieters ergeben provider_rejected_request. |
| Gesamtgröße (Megapixel) | Höchstens 16 Megapixel je Anfrage (n × aufgerundete Einheiten von 1024 × 1024 Pixeln je Bild: 1024x1024 = 1 Einheit → bis zu 10 Bilder; 1536x1024 = 2 Einheiten; 2048x2048 = 4 Einheiten → bis zu 4 Bilder; sonst 400 invalid_image_request). |
| Abrechnung & Startguthaben | Je nach Modell pro Bild (data-Anzahl) oder pro Megapixel (aus Antwort-size, sonst Anfrage-size, sonst 1024x1024; siehe Modelle & Preise). Nicht im Startguthaben freigegebene verwaltete Modelle liefern 403 starter_model_not_allowed. |
| Streaming & Unterrouten | Nur POST (sonst 405 method_not_allowed); "stream": true liefert 400 streaming_not_supported_for_endpoint; /v1/images/edits und weitere Pfade unter /v1/images/ liefern 404 unsupported_endpoint. |
| 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 | streaming_not_supported_for_endpoint | Die Anfrage verlangt Streaming, der Endpunkt unterstützt es aber nicht. |
| 400 | invalid_request_body | Der Body ist kein JSON-Objekt oder nicht in UTF-8 kodiert. |
| 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_image_request | prompt, n oder size liegt außerhalb der Grenzen des Gateways; message nennt den Parameter. |
| 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 | 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 | 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. |
| 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 | model_not_available | Die Modell-ID ist für die Organisation nicht verfügbar. |
| 405 | method_not_allowed | Der Endpunkt nimmt nur POST an. |
| 413 | request_too_large | Der Body überschreitet das Größenlimit des Endpunkts. |
| 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. |
| 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. |
| 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. |
| 504 | provider_timeout | Der Anbieter hat nicht innerhalb der Wartezeit des Gateways geantwortet. Die Antwort enthält Retry-After mit 10 Sekunden. |
Dateien & Skills.
Unter Models → Shield (Bereich Erweiterte Einstellungen) steuert der Schalter Dateianhänge und Bilder in Anfragen erlauben (allow_file_content, Standard: an) alle Dateipfade. Ist er ausgeschaltet, lehnt das Gateway Nachrichten mit Datei-, Bild-, Audio- oder file_id-Teilen sowie alle Aufrufe an /v1/files, /v1/skills und /v1/audio/transcriptions mit 403 file_content_not_allowed ab.
Eingebettete Dateien (mit Shield-Prüfung für UTF-8-Text)
Sendest du Dateien inline als Base64-data:-URL an /v1/chat/completions, /v1/responses oder /v1/messages, prüft Noirdoc Shield eingebettete UTF-8-Textdateien (text/*, JSON, XML, CSV, Markdown, YAML unter 4 MiB dekodiert; maximal 4 MiB geprüfter Text insgesamt oder 413 shield_input_too_large) vor der Weiterleitung. Binärdokumente (PDF, DOCX, XLSX, PPTX), Bilder, Audio sowie file_id-Verweise kann Shield nicht als Text lesen: Unter enforced folgt 422 shield_uninspectable_content (extrahiere Text dann vorab clientseitig); ohne enforced prüft Shield alle Textfelder und markiert die Antwort mit X-Noirdoc-Shield: partial; redacted=<n> sowie X-Noirdoc-Masked: false.
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": [
{"type": "text", "text": "Fasse die Notizen zusammen."},
{
"type": "file",
"file": {
"filename": "notizen.txt",
"file_data": "data:text/plain;base64,Sm9uYXMgQmVja2Vy..."
}
}
]
}]
}'Durchleitung über /v1/files und /v1/skills
/v1/files und /v1/skills leiten Uploads, Abrufe und Löschungen unverändert und ohne Shield-Prüfung an den Anbieter weiter (Body bis 600 MB, keine zusätzliche Gateway-Gebühr).
POST https://api.noirdoc.de/v1/files
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.noirdoc.de/v1",
api_key=os.environ["NOIRDOC_API_KEY"],
)
with open("vertrag.pdf", "rb") as f:
uploaded = client.files.create(file=f, purpose="user_data")
print(uploaded.id)import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.noirdoc.de/v1",
apiKey: process.env.NOIRDOC_API_KEY,
});
const uploaded = await client.files.create({
file: fs.createReadStream("vertrag.pdf"),
purpose: "user_data",
});
console.log(uploaded.id);curl https://api.noirdoc.de/v1/files \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "X-Provider: anthropic" \
-F file="@vertrag.pdf"// 200 OK · X-Noirdoc-Masked: false
{
"id": "file-7f3a91c2",
"object": "file",
"bytes": 184320,
"created_at": 1763180400,
"filename": "vertrag.pdf",
"purpose": "user_data",
}| Bereich | Verhalten bei Noirdoc |
|---|---|
Fail-closed bei enforced | Da /v1/files und /v1/skills keine Shield-Prüfung ausführen, lehnt das Gateway unter enforced oder mit X-Noirdoc-Mask: on alle schreibenden Methoden (außer GET, HEAD, OPTIONS, DELETE) mit 403 masking_not_supported_for_endpoint ab. Auflisten, Abrufen, GET /v1/files/{id}/content und Löschen bleiben erlaubt. |
Anbieter-Auswahl (X-Provider) | Beide Routen tragen kein model und gehen an den ältesten aktiven Anbieter des gewählten Formats (BYOK vorrangig; Claude über Google Vertex entfällt; ohne passenden Anbieter 502 provider_not_configured; Anbieter- und Startguthaben-Regeln wie starter_model_not_allowed gelten weiter). Auf /v1/files wählt Authorization: Bearer oder api-key das OpenAI-Format und x-api-key das Anthropic-Format; X-Provider: anthropic oder X-Provider: openai (kleingeschrieben) übersteuert die Auswahl. /v1/skills nutzt immer Anthropic (X-Provider wirkt dort nicht). Für Anthropic ergänzt das Gateway anthropic-beta um files-api-2025-04-14 bzw. skills-2025-10-02. |
| Verwaltete Anbieter | Auf gemeinsamen Plattform-Konten trennt das Gateway alle Objekte je Organisation: Listen zeigen nur eigene Dateien sowie vorgefertigte Anthropic-Skills (Seiten können daher kürzer sein als limit), fremde {id}-Zugriffe liefern 404 object_not_found, nicht freigegebene Methoden 403 endpoint_not_available_on_platform, ein Ausfall der Zuordnungsprüfung 503 ownership_check_unavailable. Auf BYOK-Routen entfällt diese Trennung. |
| Unterrouten & Header | Unterstützt sind POST|GET /v1/files, GET|DELETE /v1/files/{id}, GET /v1/files/{id}/content sowie /v1/skills, /v1/skills/{id}, /v1/skills/{id}/versions und /v1/skills/{id}/versions/{version} (andere Unterpfade: 404 unsupported_endpoint). Erfolgreiche Durchleitungen tragen X-Noirdoc-Masked: false ohne X-Noirdoc-Provider und X-Noirdoc-Shield (Anbieterfehler nennen X-Noirdoc-Provider). |
Klassische Dateianalyse (Auslauf zum
2026-11-30): Bestandsorganisationen, die im Übergangsbetrieb bis zum30.11.2026noch die klassische Maskierung nutzen, wertenfile_analysis_mode(passthrough,detect_only,pseudonymize,blockmit 403file_pii_blocked) für eingebettete Dokumente bis standardmäßig 25 MB aus (bei Überschreitung oder unlesbarem Format inpseudonymize/block: 422file_unprocessable, inklusive Rückübersetzung beiGET /v1/files/{id}/content). Mit der Umstellung auf Noirdoc Shield unter Models → Shield entfallen diese Modi zugunsten der zustandslosen UTF-8-Textprüfung.
| Status | Code | Bedeutung |
|---|---|---|
| 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 | 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 | 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. |
| 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. |
| 404 | unsupported_endpoint | Das Gateway kennt diesen Pfad nicht. |
| 404 | object_not_found | Das Objekt (Datei, Skill oder gespeicherte Antwort) existiert nicht oder gehört nicht deiner Organisation. |
| 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. |
| 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 | 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. |
| 500 | file_analysis_error | Reserviert für Fehler der Dateianalyse. Das Gateway sendet diesen Code derzeit nicht. |
| 502 | provider_not_configured | Für diese Anfrage ist in der Organisation kein passender Anbieter eingerichtet. |
| 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. |