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.

Python
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"
TypeScript
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
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
HTTP/2 200
content-type: application/json
x-noirdoc-provider: aki-io

Auch 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:

MechanismusRegel 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ätsgrenzenPro 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 GrenzenBei 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 VersuchAndere 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:

Erlaubte Modelle prüfen
Python
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])
TypeScript
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
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.

EinstellungWirkung & Fehlercode bei Ausschluss
Erlaubte ModelleAlle 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.
DatenresidenzBegrenzt 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-ExpositionSchließt Anbieter aus, die dem US CLOUD Act unterliegen (403 provider_not_allowed_for_key / provider_not_allowed_for_tag).
Nur §203-abgedeckte ProviderLässt ausschließlich Anbieter mit Vereinbarung nach § 203 StGB zu – einschließlich eigener BYOK-Anbieter.
ProviderErlaubt nur ausgewählte Anbieter; ein einzelner gewählter Anbieter bindet den Schlüssel bzw. das Tag fest an diese Route.
StartguthabenVor 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 / KatalogwertVerwaltete AnbieterEigene Anbieter (BYOK)Technische Wirkung
Katalogstatus covered (§203 abgedeckt)ZulässigZulä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) / noneAusgeschlossenStandardwert noneon_request ist ein reiner Anzeigewert und wird vom Gateway wie none behandelt.
Modus der OrganisationNur coveredAlle erlaubtFiltert 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 coveredNur coveredStrenger 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_responses unter 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.