Anbieter, Routing & § 203.
Wie das Gateway Anbieter auswählt, bei Ausfällen umschaltet, Modelle je Schlüssel oder Tag einschränkt und § 203 StGB technisch durchsetzt.
In deiner Anfrage nennst du die Modell-ID, nicht den Anbieter: Das Gateway filtert alle zulässigen Anbieter für Endpunkt-Familie, API-Format (Anthropic-Format über /v1/messages, OpenAI-kompatible Routen über /v1/chat/completions und Geschwister-Endpunkte), Organisation, Schlüssel und Request-Tags und nennt den ausführenden Partner im Antwort-Header X-Noirdoc-Provider.
from openai import OpenAI
client = OpenAI(base_url="https://api.noirdoc.de/v1")
raw = client.chat.completions.with_raw_response.create(
model="qwen3.8-27b",
messages=[{"role": "user", "content": "Prüfe Frist in § 6."}],
)
print(raw.headers.get("x-noirdoc-provider")) # z. B. "aki-io"import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.noirdoc.de/v1" });
const { data, response } = await client.chat.completions
.create({
model: "qwen3.8-27b",
messages: [{ role: "user", content: "Prüfe Frist in § 6." }],
})
.withResponse();
console.log(response.headers.get("x-noirdoc-provider"));curl -i https://api.noirdoc.de/v1/chat/completions \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-27b",
"messages": [{"role": "user", "content": "Prüfe Frist in § 6."}]
}'HTTP/2 200
content-type: application/json
x-noirdoc-provider: aki-ioAuch Fehlerantworten mit Anbieterbeteiligung tragen X-Noirdoc-Provider; antwortet ein Anbieter beim Streaming erst nach mehr als 15 Sekunden, erscheint stattdessen die SSE-Kommentarzeile : provider=<slug> (siehe Streaming).
Reihenfolge, Kapazität und Failover.
Für jede Anfrage bestimmt das Gateway deterministisch die Reihenfolge der zulässigen Anbieter und übernimmt Kapazitätssteuerung sowie automatischen Failover vor dem ersten Antwort-Byte:
| Mechanismus | Regel im Gateway |
|---|---|
Primäre Sortierung (1–5) | 1. Eigene Anbieter-Schlüssel (BYOK unter Models → Provider, owned_by: "personal") haben Vorrang vor verwalteten Anbietern ("platform"). 2. Vollständiger Modellpreis vor Routen ohne Preis. 3. Niedrigster gewichteter Preis je 1 Mio. Tokens (3 × Eingabe + 1 × Ausgabe, ohne Cache-Preise). 4. Höhere Gateway-Priorität (bevorzugt deutsche DE- und souveräne EU-Rechenzentren bei gleichem Preis). 5. Längere Zugehörigkeit im Katalog. |
| Kapazitätsgrenzen | Pro Anbieter überwacht das Gateway gleichzeitige Anfragen und Zeitfenster. Ist der erste Anbieter ausgelastet, rückt sofort der nächste freie Anbieter in Failover-Reihenfolge nach. Sind vor dem Versand alle zulässigen Anbieter ausgelastet, wartet das Gateway bis zu 10 s und antwortet danach mit 503 capacity_exhausted samt Retry-After. |
Automatischer Failover (max. 3 Anbieter) | Wechselt vor dem ersten gesendeten Antwort-Header bei Verbindungs-/Timeout-Fehlern oder Status 401, 402, 429 und 5xx auf den nächsten zulässigen Anbieter – sortiert zuerst nach Priorität, dann nach Preis. Nach Beginn eines Streams findet kein Wechsel mehr statt. Noirdoc Shield läuft einmal vor dem ersten Versuch, sodass jeder Folgeversuch denselben bereinigten Text erhält. |
429-Pausen & harte Grenzen | Bei 429 eines verwalteten Anbieters pausiert das Gateway ihn für Retry-After begrenzt auf 1–60 s (10 s ohne Header, 60 s bei erschöpftem Kontingent; BYOK wird nie pausiert). Ein Wechsel von BYOK auf verwaltete Anbieter oder von bepreisten auf unbepreiste Routen ist ausgeschlossen. |
| Fehlerabbildung nach letztem Versuch | Andere 4xx-Antworten (sowie 401, 402, 403, 429 auf BYOK-Routen) gibt das Gateway ohne weiteren Versuch als provider_rejected_request durch. Scheitert auch der letzte verwaltete Anbieter, meldet das Gateway 429 resource_exhausted (aus 429/402), provider_overloaded (503 auf OpenAI-Routen bzw. 529 auf /v1/messages und /v1/skills, jeweils mit Retry-After), 502 provider_error, 502 provider_unreachable oder 504 provider_timeout. |
Modelle und Anbieter einschränken.
Ein neuer API-Schlüssel erreicht standardmäßig alle für deine Organisation freigegebenen Modelle. Einschränkungen setzt du pro Schlüssel unter Models → API-Schlüssel sowie pro Request-Tag unter Models → Tags oder /v1/tags; GET /v1/models gibt exakt die für Schlüssel, Organisation und übergebene Tags verbleibende Modellmenge zurück:
from openai import OpenAI
client = OpenAI(base_url="https://api.noirdoc.de/v1")
models = client.models.list(
extra_headers={"X-Noirdoc-Tags": "mandat-2026-042"}
)
print([m.id for m in models.data])import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.noirdoc.de/v1" });
const page = await client.models.list({
headers: { "X-Noirdoc-Tags": "mandat-2026-042" },
});
console.log(page.data.map((m) => m.id));curl https://api.noirdoc.de/v1/models \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "X-Noirdoc-Tags: mandat-2026-042" \
| jq -r '.data[].id'Bei mehreren Tags in X-Noirdoc-Tags gilt die Schnittmenge: Modell und Anbieter müssen für die Organisation, den Schlüssel und jedes genannte Tag erlaubt sein.
| Einstellung | Wirkung & Fehlercode bei Ausschluss |
|---|---|
| Erlaubte Modelle | Alle Modelle (Standard, schließt künftige Modelle ein) oder Nur ausgewählte Modelle. Nicht enthaltene IDs enden vor der Weiterleitung mit 403 model_not_allowed_for_key bzw. 403 model_not_allowed_for_tag. |
| Datenresidenz | Begrenzt Anbieter auf gewählte Standorte (z. B. DE für deutsche Rechenzentren; EU umfasst auch Standorte in EU-Mitgliedstaaten). Ohne Auswahl ist jeder Standort zulässig. |
| Nur ohne CLOUD-Act-Exposition | Schließt Anbieter aus, die dem US CLOUD Act unterliegen (403 provider_not_allowed_for_key / provider_not_allowed_for_tag). |
| Nur §203-abgedeckte Provider | Lässt ausschließlich Anbieter mit Vereinbarung nach § 203 StGB zu – einschließlich eigener BYOK-Anbieter. |
| Provider | Erlaubt nur ausgewählte Anbieter; ein einzelner gewählter Anbieter bindet den Schlüssel bzw. das Tag fest an diese Route. |
| Startguthaben | Vor der ersten bestätigten Aufladung sind bei verwalteten Anbietern nur Modelle mit starter_allowed: true aufrufbar (siehe Schlüssel, Tags & Budgets). Nicht freigegebene Anbieter überspringt das Gateway und antwortet nur dann kostenlos mit 403 starter_model_not_allowed, wenn kein freigegebener Anbieter übrig bleibt; BYOK ist nicht betroffen. |
Berufsgeheimnisträger (§ 203 StGB).
Anwältinnen, Steuerberater, Ärztinnen und andere Berufsgeheimnisträger dürfen fremde Geheimnisse nur Dienstleistern offenbaren, die nach § 203 StGB zur Verschwiegenheit verpflichtet sind. Ob deine Organisation als Berufsgeheimnisträger eingestuft ist, legt die Frage auf Erste Schritte fest (bis zur Beantwortung aktiv, Abschalten erfordert ausdrückliche Bestätigung; im Portal unter Models → Shield als Kennzeichen §203-Mandant sichtbar):
| Ebene / Katalogwert | Verwaltete Anbieter | Eigene Anbieter (BYOK) | Technische Wirkung |
|---|---|---|---|
Katalogstatus covered (§203 abgedeckt) | Zulässig | Zulässig (sofern markiert) | Anbieter ist in Anlage 4 des AVV aufgeführt und nach § 203 StGB verpflichtet (Hintergrund unter KI für Berufsgeheimnisträger). |
Katalogstatus on_request (§203 auf Anfrage) / none | Ausgeschlossen | Standardwert none | on_request ist ein reiner Anzeigewert und wird vom Gateway wie none behandelt. |
| Modus der Organisation | Nur covered | Alle erlaubt | Filtert GET /v1/models, Routing, Failover und modellfreie Endpunkte wie /v1/files. Bleibt kein Anbieter übrig, antwortet das Gateway mit 403 provider_not_allowed_for_tenant (der Wire-Code bezeichnet die Organisation). |
Schlüssel / Tag (Nur §203-abgedeckte Provider) | Nur covered | Nur covered | Strenger als der Organisationsmodus: Da eigene BYOK-Anbieter im Portal keine covered-Markierung tragen, schließt diese Option auch BYOK-Routen mit 403 provider_not_allowed_for_key bzw. provider_not_allowed_for_tag aus. |
Speicherung beim Anbieter: Die §-203-Prüfung wählt zulässige Anbieter aus, steuert aber keine Zustandsspeicherung. Ob verwaltete Anbieter Eingabe und Antwort der Responses API für 30 Tage speichern dürfen, regelt getrennt die Option Responses-API Speicherung beim Anbieter erlauben (
allow_stored_responsesunter Models → Shield → Erweiterte Einstellungen, für neue Organisationen standardmäßig aus; siehe Chat & Responses).
| Status | Code | Bedeutung |
|---|---|---|
| 400 | wrong_endpoint_for_model | Das Modell gehört zu einer anderen Endpunkt-Familie oder einem anderen API-Format als der aufgerufene Endpunkt. |
| 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 | 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. |
| 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. |
| 502 | provider_unreachable | Das Gateway konnte keine Verbindung zum Anbieter herstellen, oder die Verbindung ist abgebrochen. |
| 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. |
| 504 | provider_timeout | Der Anbieter hat nicht innerhalb der Wartezeit des Gateways geantwortet. Die Antwort enthält Retry-After mit 10 Sekunden. |