Anbieter & Routing — Noirdoc Docs

Eine Modell-ID kann bei mehreren Anbietern verfügbar sein. In der Anfrage wählen Sie das Modell, nicht den Anbieter. Das Gateway wählt für jede Anfrage den Anbieter und nennt ihn in der Antwort im Header X-Noirdoc-Provider.

Mögliche Anbieter

Für eine Anfrage kommen die Anbieter in Frage, die das angefragte Modell führen und alle Bedingungen erfüllen:

Das Modell passt zum Endpunkt. Ein Chat-Modell ist zum Beispiel nicht über /v1/embeddings aufrufbar. Auch das API-Format des Anbieters muss passen: Modelle von Anbietern im Anthropic-Format rufen Sie über /v1/messages auf, alle anderen über die OpenAI-kompatiblen Endpunkte.
Der Anbieter ist für Berufsgeheimnisträger zugelassen, falls Ihre Organisation so eingestuft ist.
Der Anbieter erfüllt die Einschränkungen des Schlüssels: erlaubte Anbieter, Datenresidenz, CLOUD Act und § 203.
Das Modell gehört zu den erlaubten Modellen des Schlüssels, falls der Schlüssel welche festlegt.

Eigene Anbieter-Schlüssel (BYOK) haben Vorrang: Hat Ihre Organisation unter Models → Provider einen eigenen Anbieter für die Modell-ID eingerichtet, berücksichtigt das Gateway für diese Modell-ID nur Ihre eigenen Anbieter. Von Noirdoc verwaltete Anbieter kommen nur in Frage, wenn Ihre Organisation keinen eigenen Anbieter für die Modell-ID hat und verwaltete Modelle für sie freigeschaltet sind.

Die Bedingungen prüft das Gateway der Reihe nach. Bleibt nach einer Bedingung kein Anbieter übrig, antwortet es mit dem Fehler dieser Bedingung:

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.
404	`model_not_available`	Die Modell-ID ist für die Organisation nicht verfügbar.

Wie Sie Modelle und Anbieter für einen Schlüssel einschränken, zeigt Modelle & Anbieter einschränken.

Reihenfolge der Anbieter

Das Gateway sortiert die möglichen Anbieter nach diesen Regeln. Die erste Regel, die einen Unterschied macht, entscheidet:

Eigene Anbieter (BYOK) vor verwalteten Anbietern.
Anbieter mit vollständigem Preis für das Modell vor Anbietern ohne Preis.
Der günstigere Anbieter vor dem teureren. Das Gateway vergleicht einen gewichteten Preis je 1 Mio. Tokens: dreimal der Eingabepreis plus einmal der Ausgabepreis. Die Gewichtung bildet typische Anfragen ab, die viel mehr Eingabe als Ausgabe enthalten. Preise für den Cache zählen dabei nicht.
Bei gleichem Preis der Anbieter, der länger im Katalog ist.

Die Reihenfolge ist fest und hängt nicht vom Zufall oder von der Auslastung ab. Dieselbe Anfrage geht bei gleichem Katalog immer zuerst an denselben Anbieter. GET /v1/models listet jede Modell-ID, die Ihr Schlüssel aufrufen darf, genau einmal. Das Feld owned_by zeigt, ob der erste Anbieter ein eigener ist (personal) oder ein von Noirdoc verwalteter (platform).

Failover

Failover heißt: Scheitert ein Anbieter, fällt das Gateway auf den nächsten Anbieter der Reihenfolge zurück. Das Gateway versucht höchstens drei Anbieter je Anfrage.

Es wechselt den Anbieter bei diesen Fehlern:

Der Anbieter ist nicht erreichbar, oder die Verbindung läuft in eine Zeitüberschreitung.
Der Anbieter antwortet mit Statuscode 429 oder einem Statuscode 5xx.

Jeder andere Statuscode 4xx ist die Antwort des Anbieters auf die Anfrage selbst. Das Gateway gibt ihn unverändert zurück und versucht keinen weiteren Anbieter.

Das Gateway wechselt nur, solange Ihre Anwendung noch nichts von der Antwort erhalten hat. Es entscheidet anhand des Statuscodes, den der Anbieter mit den Headern seiner Antwort sendet. Bricht ein Stream danach ab, wechselt das Gateway nicht mehr.

Zwei Regeln begrenzen den Failover:

Das Gateway wechselt nie von einem eigenen Anbieter (BYOK) zu einem verwalteten Anbieter. Sonst entstünden Kosten bei Noirdoc, obwohl Sie Ihren eigenen Anbieter-Schlüssel nutzen wollten.
Das Gateway wechselt nie von einem Anbieter mit Preis zu einem ohne Preis.

Scheitert auch der letzte Anbieter, erhält Ihre Anwendung dessen Fehler. Eine Antwort des Anbieters mit Statuscode 429 oder 5xx gibt das Gateway unverändert weiter. Konnte das Gateway den Anbieter gar nicht erreichen, antwortet es selbst:

Status	Code	Bedeutung
502	`provider_unreachable`	Das Gateway konnte keine Verbindung zum Anbieter herstellen, oder die Verbindung ist abgebrochen.
504	`provider_timeout`	Der Anbieter hat nicht innerhalb der Wartezeit des Gateways geantwortet.

Die Maskierung läuft einmal vor dem ersten Versuch. Jeder weitere Anbieter erhält dieselbe maskierte Anfrage.

Anbieter in der Antwort

Bei Anfragen mit Modell-ID enthält die Antwort den Header X-Noirdoc-Provider. Er nennt den Kurznamen des Anbieters, der die Anfrage beantwortet hat. Nach einem Failover ist das der Anbieter, der zuletzt geantwortet hat. Auch eine Fehlerantwort des Anbieters trägt den Header.

Shell

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": "Hallo"}]
  }'

HTTP

HTTP/2 200
content-type: application/json
x-noirdoc-provider: aki-io

In den SDKs lesen Sie den Header über die rohe Antwort. Die Anleitung OpenAI-SDK zeigt das für Python und TypeScript.