Embeddings & Rerank.
Erzeugt Vektor-Embeddings und sortiert Suchtreffer nach Relevanz, jeweils mit zustandsloser Eingabeprüfung durch Noirdoc Shield.
Embeddings.
Nimmt Anfragen im Format der OpenAI Embeddings API entgegen (endpoint_family: "embeddings" in GET /v1/models) und leitet Zusatzfelder wie encoding_format und dimensions unverändert an den Anbieter weiter.
POST https://api.noirdoc.de/v1/embeddings
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.noirdoc.de/v1",
api_key=os.environ["NOIRDOC_API_KEY"],
)
res = client.embeddings.create(
model="BAAI/bge-m3",
input=[
"Die Kündigungsfrist beträgt drei Monate.",
"Der Vertrag endet zum Quartalsende.",
],
extra_headers={"X-Noirdoc-Shield": "on"},
)
print(len(res.data[0].embedding))import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.noirdoc.de/v1",
apiKey: process.env.NOIRDOC_API_KEY,
});
const res = await client.embeddings.create(
{
model: "BAAI/bge-m3",
input: [
"Die Kündigungsfrist beträgt drei Monate.",
"Der Vertrag endet zum Quartalsende.",
"Die Verlängerung beträgt jeweils zwölf Monate.",
],
},
{ headers: { "X-Noirdoc-Shield": "on" } },
);
console.log(res.data[0]?.embedding.length);curl https://api.noirdoc.de/v1/embeddings \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Noirdoc-Shield: on" \
-d '{
"model": "BAAI/bge-m3",
"input": [
"Die Kündigungsfrist beträgt drei Monate.",
"Der Vertrag endet zum Quartalsende."
]
}'// 200 OK · X-Noirdoc-Provider: ionos · X-Noirdoc-Shield: redacted=0
{
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [0.0184, -0.0291, 0.0412],
},
{
"object": "embedding",
"index": 1,
"embedding": [-0.0093, 0.0318, 0.0127],
},
],
"model": "BAAI/bge-m3",
"usage": {
"prompt_tokens": 19,
"total_tokens": 19,
},
}| Bereich | Verhalten bei Noirdoc |
|---|---|
model | Modell-ID der Familie embeddings aus GET /v1/models (andere Modellfamilien ergeben 400 wrong_endpoint_for_model). Im Startguthaben sind nur freigegebene Modelle aufrufbar, andere verwaltete Modelle liefern 403 starter_model_not_allowed (Guthaben). Im Antwortfeld model steht wieder die von dir gesendete ID. |
| Noirdoc Shield | Bei aktiver Prüfung (default_on, enforced, shield_mode: on auf Schlüssel oder Tag oder X-Noirdoc-Shield: on) prüft Shield String-Eingaben, String-Arrays, multimodale Textfelder sowie ganzzahlige Token-Arrays (dekodiert über tiktoken, geschwärzt und wieder als Token-IDs kodiert). Die Antwort trägt X-Noirdoc-Shield: redacted=<n> und X-Noirdoc-Masked: true; block-Treffer brechen mit 403 shield_violation ab (Geprüfte Felder). Bestandsorganisationen in der klassischen Maskierung bis zum 30.11.2026 erhalten bei enforced oder X-Noirdoc-Mask: on 403 masking_not_supported_for_endpoint, solange kein X-Noirdoc-Shield: on gesetzt ist. |
| Streaming | Nicht unterstützt. "stream": true beantwortet das Gateway mit 400 streaming_not_supported_for_endpoint. |
| Abrechnung | Eingabe-Tokens aus usage (fehlt die Angabe beim Anbieter, schätzt das Gateway sie aus dem Body), zuzüglich Noirdoc Shield bei aktiver Prüfung (Shield). |
| Unterrouten & Header | Keine Unterrouten (andere Pfade unter /v1/embeddings/ liefern 404 unsupported_endpoint). X-Noirdoc-Provider nennt den Anbieter; API-Schlüssel, X-Noirdoc-Shield und X-Noirdoc-Mask werden vor der Weiterleitung entfernt. |
| 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 | 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 | 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 | 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. |
| 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 | 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. |
| 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. |
| 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. |
| 504 | provider_timeout | Der Anbieter hat nicht innerhalb der Wartezeit des Gateways geantwortet. Die Antwort enthält Retry-After mit 10 Sekunden. |
Rerank.
Bewertet und sortiert Kandidatendokumente nach ihrer Relevanz für eine Suchanfrage (endpoint_family: "rerank" in GET /v1/models) und gibt ein über alle Anbieter normiertes Antwortformat zurück.
POST https://api.noirdoc.de/v1/rerank
import os
import httpx
res = httpx.post(
"https://api.noirdoc.de/v1/rerank",
headers={
"Authorization": f"Bearer {os.environ['NOIRDOC_API_KEY']}",
"X-Noirdoc-Shield": "on",
},
json={
"model": "Qwen/Qwen3-VL-Reranker-8B",
"query": "Wie lange ist die Kündigungsfrist?",
"documents": [
"Der Vertrag endet zum Quartalsende.",
"Die Kündigungsfrist beträgt drei Monate.",
"Die Miete ist zum Monatsersten fällig.",
],
"top_n": 2,
"return_documents": True,
},
)
res.raise_for_status()
print(res.json()["results"][0])const res = await fetch("https://api.noirdoc.de/v1/rerank", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.NOIRDOC_API_KEY}`,
"Content-Type": "application/json",
"X-Noirdoc-Shield": "on",
},
body: JSON.stringify({
model: "Qwen/Qwen3-VL-Reranker-8B",
query: "Wie lange ist die Kündigungsfrist?",
documents: [
"Der Vertrag endet zum Quartalsende.",
"Die Kündigungsfrist beträgt drei Monate.",
"Die Miete ist zum Monatsersten fällig.",
],
top_n: 2,
return_documents: true,
}),
});
const data = await res.json();
console.log(data.results[0]);curl https://api.noirdoc.de/v1/rerank \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Noirdoc-Shield: on" \
-d '{
"model": "Qwen/Qwen3-VL-Reranker-8B",
"query": "Wie lange ist die Kündigungsfrist?",
"documents": [
"Der Vertrag endet zum Quartalsende.",
"Die Kündigungsfrist beträgt drei Monate.",
"Die Miete ist zum Monatsersten fällig."
],
"top_n": 2,
"return_documents": true
}'// 200 OK · X-Noirdoc-Provider: weber · X-Noirdoc-Shield: redacted=0
{
"results": [
{
"index": 1,
"relevance_score": 0.94,
"document": {
"text": "Die Kündigungsfrist beträgt drei Monate.",
},
},
{
"index": 0,
"relevance_score": 0.31,
"document": {
"text": "Der Vertrag endet zum Quartalsende.",
},
},
],
"usage": {
"total_tokens": 48,
},
}| Feld / Bereich | Regel bei Noirdoc |
|---|---|
model (Pflicht) | Modell-ID der Familie rerank aus GET /v1/models (andere Familien liefern 400 wrong_endpoint_for_model; nicht im Startguthaben freigegebene verwaltete Modelle liefern 403 starter_model_not_allowed). |
query & documents (Pflicht) | query als nicht leerer String; documents als Liste von 1 bis 1.000 Strings. Bilder oder content-Arrays lehnt das Gateway vorab mit 400 invalid_rerank_request ab. |
instruction, top_n, return_documents | Alle optional: instruction als Aufgaben-String, top_n als ganze Zahl ab 1 (begrenzt die Trefferzahl; < 1 ergibt 400 invalid_rerank_request), return_documents: true ergänzt den Dokumenttext in der Antwort. |
| Normierte Antwort | results[] enthält index (Position in documents ab 0), relevance_score (modellspezifische Skala — nur innerhalb derselben Antwort vergleichbar) und document als Objekt {"text": "…"} (bei geschwärzten Eingaben in der geschwärzten Fassung), dazu usage. |
| Noirdoc Shield | Prüft query, instruction und documents[] vor der Weiterleitung (X-Noirdoc-Shield: redacted=<n>, X-Noirdoc-Masked: true, bei block-Treffern 403 shield_violation). In der klassischen Maskierung bis 30.11.2026 führen enforced und X-Noirdoc-Mask: on ohne X-Noirdoc-Shield: on zu 403 masking_not_supported_for_endpoint. |
| Streaming, Methoden & Abrechnung | Nur POST (sonst 405 method_not_allowed); "stream": true ergibt 400 streaming_not_supported_for_endpoint; Pfade unter /v1/rerank/ liefern 404 unsupported_endpoint. Abrechnung je Modell nach Eingabe-Tokens (per1MTokens, bei fehlendem usage geschätzt) oder pauschal je Anfrage (perRequest über price_input), zuzüglich Shield (Modelle & Preise). |
Prompt-Tags für Qwen3-Reranker
Qwen3-Reranker-Modelle erzielen die beste Trennschärfe, wenn query die Tags <Instruct>: und <Query>: trägt und jedes Element in documents mit <Document>: beginnt. Das Gateway verändert die Texte nicht selbst, sondern leitet deine Strings unverändert weiter:
instruct = "Finde Vertragsklauseln, die die Frage beantworten."
question = "Wie lange ist die Kündigungsfrist?"
docs = [
"Der Vertrag endet zum Quartalsende.",
"Die Kündigungsfrist beträgt drei Monate.",
]
payload = {
"model": "Qwen/Qwen3-VL-Reranker-8B",
"query": f"<Instruct>: {instruct}\n<Query>: {question}",
"documents": [f"<Document>: {d}" for d in docs],
}| 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 | 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_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. |
| 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 | 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 | 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. |
| 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 | 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. |
| 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. |
| 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. |
| 504 | provider_timeout | Der Anbieter hat nicht innerhalb der Wartezeit des Gateways geantwortet. Die Antwort enthält Retry-After mit 10 Sekunden. |