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'."
  }
}

Feld	Beschreibung
type	Fehlerkategorie (z. B. proxy_error, auth_error, validation_error)
code	Maschinenlesbarer Fehlercode für die programmatische Behandlung
message	Lesbare 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.

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/embeddings' 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.

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).

Standard-HTTP-Fehlercodes

Zusaetzlich zu den Noirdoc-spezifischen Codes oben verwendet die API Standard-HTTP-Statuscodes:

Status	Code	Beschreibung
401	unauthorized	Fehlende, ungueltige oder abgelaufene Authentifizierungsdaten
403	forbidden	Gueltige Anmeldedaten, aber unzureichende Berechtigungen
404	not_found	Die angeforderte Ressource existiert nicht
422	validation_error	Der Request-Body hat die Validierung nicht bestanden — pruefen Sie Pflichtfelder und Typen
429	rate_limited	Zu viele Anfragen — warten Sie und versuchen Sie es erneut unter Beachtung des Retry-After-Headers

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": "gpt-5.4-mini",
        "messages": [{"role": "user", "content": "Hallo"}]
    }
)

if response.status_code >= 400:
    error = response.json()["error"]
    code = error["code"]

    if code == "provider_not_configured":
        print("Konfigurieren Sie Ihren Provider im Noirdoc-Portal.")
    elif code == "provider_timeout":
        print("Provider-Timeout. Erneuter Versuch...")
    elif code == "rate_limited":
        retry_after = response.headers.get("Retry-After", "60")
        print(f"Rate Limit erreicht. Erneuter Versuch nach {retry_after}s.")
    else:
        print(f"Fehler: {error['message']}")