Fehlercodes

Fehlerantwort-Format und alle Fehlercodes.

Fehlerantwort-Format

Alle Noirdoc-API-Fehler folgen einem einheitlichen JSON-Envelope:

{
  "error": {
    "type": "proxy_error",
    "code": "provider_not_configured",
    "message": "No API key configured for provider 'openai'."
  }
}
FeldBeschreibung
typeFehlerkategorie — bei Proxy-Fehlern immer proxy_error
codeMaschinenlesbarer Fehlercode für die programmatische Behandlung
messageLesbare Beschreibung des aufgetretenen Fehlers

Verwenden Sie bei der programmatischen Fehlerbehandlung immer das Feld code. Der Wert von message kann sich zwischen Versionen aendern, aber die code-Werte sind stabil.

Proxy-Fehlercodes

Diese Fehler werden von den /v1/*-Proxy-Endpunkten zurueckgegeben, wenn Anfragen an Upstream-LLM-Provider weitergeleitet werden.

provider_not_configured

HTTP-Status: 502

Fuer den angeforderten Provider wurde kein API-Key konfiguriert. Beispielsweise wenn Sie eine Anfrage mit einem OpenAI-Modell senden, aber für Ihren Tenant kein OpenAI-Provider eingerichtet ist.

{
  "error": {
    "type": "proxy_error",
    "code": "provider_not_configured",
    "message": "No API key configured for provider 'openai'."
  }
}

Lösung: Konfigurieren Sie den Provider über PUT /portal/providers/{provider} oder kontaktieren Sie Ihren Admin.

Für Organisationen mit Models-Berechtigung greift bei fehlendem eigenem Key der Plattform-Fallback (nur OpenAI-kompatible Pfade). Dieser Fehler bedeutet dann: weder ein eigener Provider-Key noch der Plattform-Fallback ist für diesen Pfad verfügbar.

unsupported_endpoint

HTTP-Status: 404

Der Anfragepfad gehoert nicht zu den unterstützten Proxy-Pfaden. Noirdoc leitet Anfragen nur an bestimmte Upstream-Endpunkte weiter.

{
  "error": {
    "type": "proxy_error",
    "code": "unsupported_endpoint",
    "message": "Endpoint '/v1/audio/speech' is not supported."
  }
}

Lösung: Pruefen Sie die unterstützten Pfade und überpruefen Sie Ihre Anfrage-URL.

provider_unreachable

HTTP-Status: 502

Der Upstream-LLM-Provider hat einen Fehler zurueckgegeben oder war nicht erreichbar. Dies kann passieren, wenn der Provider Ausfallzeiten hat oder eine unerwartete Antwort liefert.

{
  "error": {
    "type": "proxy_error",
    "code": "provider_unreachable",
    "message": "Upstream provider returned HTTP 500."
  }
}

Lösung: Wiederholen Sie die Anfrage nach einer kurzen Wartezeit. Wenn das Problem bestehen bleibt, pruefen Sie die Statusseite des Providers.

provider_timeout

HTTP-Status: 504

Der Upstream-Provider hat nicht innerhalb der konfigurierten Zeitspanne geantwortet.

{
  "error": {
    "type": "proxy_error",
    "code": "provider_timeout",
    "message": "Upstream provider did not respond within 60 seconds."
  }
}

Lösung: Versuchen Sie es mit einem einfacheren Prompt oder einer kleineren Eingabe. Fuer langdauernde Anfragen sollten Sie Streaming in Betracht ziehen.

provider_error

HTTP-Status: entspricht der Antwort des Providers (≥ 400)

Der Upstream-Provider hat einen Fehler zurueckgegeben — etwa ungueltige Parameter oder ein unbekanntes Modell. Noirdoc reicht den Statuscode des Providers durch und kapselt die Meldung im Standard-Envelope.

{
  "error": {
    "type": "proxy_error",
    "code": "provider_error",
    "message": "Upstream provider returned HTTP 400."
  }
}

Lösung: Pruefen Sie die Anfrageparameter (insbesondere den Modellnamen) anhand der durchgereichten Provider-Meldung.

wrong_endpoint_for_model

HTTP-Status: 400

Das angeforderte Modell passt nicht zum aufgerufenen Endpunkt. Jedes Katalog-Modell gehoert zu genau einer Endpunkt-Familie — ein Chat-Modell kann nicht ueber /v1/embeddings aufgerufen werden und ein Embedding-Modell nicht ueber /v1/chat/completions.

{
  "error": {
    "type": "proxy_error",
    "code": "wrong_endpoint_for_model",
    "message": "Model '<model-id>' cannot be called from this endpoint; use the endpoint matching its provider's API format."
  }
}

Lösung: Verwenden Sie den zum Modell passenden Endpunkt — siehe Embeddings.

streaming_not_supported_for_endpoint

HTTP-Status: 400

Das Feld stream: true wird auf diesem Endpunkt nicht unterstützt. Manche Endpunkte der Noirdoc API akzeptieren kein Streaming — beispielsweise /v1/embeddings.

{
  "error": {
    "type": "proxy_error",
    "code": "streaming_not_supported_for_endpoint",
    "message": "Streaming is not supported on '/v1/embeddings'."
  }
}

Lösung: Senden Sie die Anfrage ohne "stream": true oder verwenden Sie einen anderen Endpunkt.

masking_not_supported_for_endpoint

HTTP-Status: 403

Die Maskierungs-Richtlinie der Organisation ist enforced, aber der aufgerufene Endpunkt unterstuetzt keine Maskierung (derzeit betrifft das /v1/embeddings). Statt die Anfrage unmaskiert weiterzuleiten, blockiert der Proxy sie. Zudem werden auch explizite X-Noirdoc-Mask: on-Header auf nicht-masking-Endpunkten mit diesem Code abgelehnt.

{
  "error": {
    "type": "proxy_error",
    "code": "masking_not_supported_for_endpoint",
    "message": "Masking is not available on '/v1/embeddings', and this tenant's mask policy requires masking on all traffic. Contact your administrator."
  }
}

Lösung: Nutzen Sie den Endpunkt nicht mit enforced-Richtlinie, oder lassen Sie die Richtlinie von Ihrem Admin auf default_on/default_off umstellen. Hintergrund: Embeddings — keine PII-Maskierung.

PII- und Datei-Fehlercodes

Diese Fehler betreffen die Pseudonymisierungs- und File-Handling-Funktionen von Noirdoc.

detection_error

HTTP-Status: 500

Die PII-Erkennungsengine ist bei der Analyse des Anfragetexts auf einen internen Fehler gestossen.

{
  "error": {
    "type": "proxy_error",
    "code": "detection_error",
    "message": "PII detection engine failed."
  }
}

Lösung: Wiederholen Sie die Anfrage. Wenn der Fehler bestehen bleibt, kontaktieren Sie den Support.

file_content_not_allowed

HTTP-Status: 403

Die Dateiverarbeitung ist für diesen Tenant deaktiviert. Die Anfrage hat versucht, eine Datei hochzuladen oder zu referenzieren, aber die Einstellungen des Tenants erlauben kein File-Handling.

{
  "error": {
    "type": "proxy_error",
    "code": "file_content_not_allowed",
    "message": "File processing is disabled for this tenant."
  }
}

Lösung: Aktivieren Sie File-Handling in den Tenant-Einstellungen über PATCH /portal/settings oder kontaktieren Sie Ihren Admin.

file_pii_blocked

HTTP-Status: 403

Die hochgeladene Datei enthaelt personenbezogene Daten und der File-Handling-Modus des Tenants ist auf block gesetzt. Noirdoc weigert sich, Dateien mit erkannten PII in diesem Modus weiterzuleiten.

{
  "error": {
    "type": "proxy_error",
    "code": "file_pii_blocked",
    "message": "File contains PII and file handling mode is 'block'."
  }
}

Lösung: Entfernen Sie personenbezogene Daten aus der Datei vor dem Upload, oder aendern Sie den File-Handling-Modus auf pseudonymize in Ihren Tenant-Einstellungen.

file_analysis_error

HTTP-Status: 500

Noirdoc konnte den Inhalt einer hochgeladenen Datei nicht extrahieren oder analysieren. Dies kann bei beschaedigten Dateien oder nicht unterstützten Dateiformaten auftreten.

{
  "error": {
    "type": "proxy_error",
    "code": "file_analysis_error",
    "message": "Failed to extract content from uploaded file."
  }
}

Lösung: Stellen Sie sicher, dass die Datei nicht beschaedigt ist und ein unterstütztes Format hat (PDF, DOCX, Bilder).

Authentifizierung & Validierung

Nicht alle Fehler verwenden den error-Envelope. Authentifizierungs- und Validierungsfehler kommen direkt vom Framework und nutzen das Standardformat { "detail": … }:

StatusBedeutungFormat
401Fehlender oder ungueltiger px--Key{ "detail": "Missing or invalid API key" }
422Der Request-Body hat die Validierung nicht bestanden{ "detail": [ … ] }

Nur die oben gelisteten Proxy-Fehler verwenden den { "error": { "type", "code", "message" } }-Envelope. Werten Sie daher zuerst den HTTP-Status aus und greifen Sie nur bei Proxy-Fehlern auf error.code zu.

Fehlerbehandlung im Code

Hier ein Python-Beispiel zur Behandlung von Noirdoc-Fehlern:

import httpx

response = httpx.post(
    "https://api.noirdoc.de/v1/chat/completions",
    headers={"Authorization": "Bearer px-your-key"},
    json={
        "model": "<model-id>",
        "messages": [{"role": "user", "content": "Hallo"}],
    },
)

if response.status_code >= 400:
    body = response.json()
    if "error" in body:  # Proxy-Fehler mit code
        code = body["error"]["code"]
        if code == "provider_not_configured":
            print("Konfigurieren Sie Ihren Provider im Noirdoc-Portal.")
        elif code == "provider_timeout":
            print("Provider-Timeout. Erneuter Versuch ...")
        else:
            print(f"Fehler: {body['error']['message']}")
    else:  # 401/422 im FastAPI-Format
        print(f"Fehler: {body.get('detail')}")