Fehler-Referenz

Alle MSV3-Gateway-Fehler folgen der gleichen JSON-Struktur:

{
  "error": "invalid_request",
  "message": "PZN must be 1-8 digits, got: 'abc123'",
  "wholesaler": "noweda",
  "error_code": "3002"
}

Feld	Immer vorhanden	Beschreibung
`error`	Ja	Maschinenlesbarer Fehlercode
`message`	Ja	Menschenlesbare Beschreibung
`wholesaler`	Bei GH-Fehlern	Der Grosshaendler, der den Fehler erzeugt hat
`error_code`	Bei GH-Ablehnungen	Roher MSV3-/Grosshaendler-Fehlercode

HTTP-Statuscodes

HTTP	Fehlercode	Wann tritt er auf
400	`invalid_request`	Falsches PZN-Format, fehlendes Pflichtfeld, ungueltiger Wert
401	`unauthorized`	Fehlender oder ungueltiger `X-API-Key`
401	`invalid_msv3_credentials`	Falscher MSV3-Benutzername oder -Passwort
404	`wholesaler_not_found`	Unbekannte Grosshaendler-ID
404	`not_found`	Ressource nicht gefunden (Dokument, Bestellung etc.)
422	`order_rejected`	Grosshaendler hat die Bestellung abgelehnt
429	`rate_limited`	Zu viele Anfragen
502	`wholesaler_unavailable`	Grosshaendler-Endpunkt nicht erreichbar oder Timeout
503	`service_unavailable`	Gateway voruebergehend nicht verfuegbar

400 - Bad Request

Fehlercode: invalid_request

Der Anfrage-Body oder die Parameter haben die Validierung nicht bestanden.

Ursache	Beispiel-Nachricht
Ungueltiges PZN-Format	`PZN must be 1-8 digits, got: 'abc123'`
Menge ausser Bereich	`quantity must be between 1 and 99999`
Fehlendes Pflichtfeld	`field 'wholesaler' is required`
Zu viele Artikel	`items array must not exceed 50 entries`
Ungueltiger Enum-Wert	`delivery_preference must be one of: normal, backorder, grouped, disposition`

Loesung: Pruefen Sie das message-Feld fuer den genauen Validierungsfehler. Korrigieren Sie die Anfrage und wiederholen Sie sie.

401 - Unauthorized

`unauthorized`

Fehlender oder ungueltiger X-API-Key-Header.

{
  "error": "unauthorized",
  "message": "Missing or invalid X-API-Key header."
}

Loesung: Stellen Sie sicher, dass X-API-Key vorhanden ist und einen gueltigen Gateway-API-Schluessel enthaelt (pk_live_... oder pk_test_...).

`invalid_msv3_credentials`

Der Grosshaendler hat die MSV3-Benutzername/Passwort-Kombination abgelehnt.

{
  "error": "invalid_msv3_credentials",
  "message": "Authentication failed at wholesaler noweda.",
  "wholesaler": "noweda"
}

Loesung: Ueberpruefen Sie X-MSV3-Username und X-MSV3-Password. Nutzen Sie POST /v1/connection/test zum Testen der Zugangsdaten.

404 - Not Found

`wholesaler_not_found`

Die angeforderte Grosshaendler-ID ist nicht im Register.

Loesung: Verwenden Sie GET /v1/wholesalers, um gueltige IDs aufzulisten. Pruefen Sie auf Tippfehler.

`not_found`

Eine bestimmte Ressource (Dokument, Bestellung) wurde nicht gefunden.

Loesung: Ueberpruefen Sie die ID und stellen Sie sicher, dass sie zum angegebenen Grosshaendler gehoert.

422 - Bestellung abgelehnt

Fehlercode: order_rejected

Der Grosshaendler hat die Anfrage akzeptiert, aber die Bestellung aus einem geschaeftlichen Grund abgelehnt.

{
  "error": "order_rejected",
  "message": "Order rejected: Artikel nicht bestellbar (3002)",
  "wholesaler": "noweda",
  "error_code": "3002"
}

MSV3-Fehlercode-Zuordnung

MSV3-Code	Bedeutung	Empfohlene Aktion
`3001`	Artikelnummer unbekannt	PZN im Grosshaendler-Katalog ueberpruefen
`3002`	Artikel nicht bestellbar	Pruefen, ob Artikel gesperrt ist; Grosshaendler kontaktieren
`3003`	Mindestbestellmenge nicht erreicht	Menge erhoehen
`3004`	Artikel eingestellt	Nachfolge-PZN bestellen
`3005`	Artikel auf Rezeptsperre	Rezept erforderlich; Grosshaendler kontaktieren
`3006`	Mengenlimit ueberschritten	Menge auf Grosshaendler-Limit reduzieren
`9001`	Allgemeine Ablehnung	Grosshaendler-Support kontaktieren

429 - Rate Limited

Fehlercode: rate_limited

Ihr API-Schluessel hat sein Anfrage-Limit ueberschritten.

{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Retry after 30 seconds."
}

Die Antwort enthaelt einen Retry-After-Header. Warten Sie die angegebene Anzahl Sekunden, bevor Sie es erneut versuchen.

502 - Grosshaendler nicht erreichbar

Fehlercode: wholesaler_unavailable

Der SOAP-Endpunkt des Grosshaendlers ist nicht erreichbar, hat ein Timeout oder eine unerwartete Antwort geliefert.

Ursache	Nachrichtenmuster
Netzwerk-Timeout	`connection timed out`
TCP-Verbindung abgelehnt	`connection refused`
TLS-Fehler	`TLS handshake failed`
Unerwarteter SOAP-Fehler	`unexpected SOAP fault: ...`

Loesung:

Mit exponentiellem Backoff wiederholen -- Grosshaendler-Ausfaelle sind typischerweise kurz.
Grosshaendler-Status mit POST /v1/connection/test pruefen.
Bei bekannter Wartung abwarten und spaeter erneut versuchen.

503 - Service nicht verfuegbar

Fehlercode: service_unavailable

Das Gateway selbst ist voruebergehend nicht verfuegbar (z.B. waehrend eines Deployments).

Loesung: Mit exponentiellem Backoff wiederholen. Wird typischerweise innerhalb von Sekunden behoben.

SDK-Fehlerhierarchie

Beide SDKs bieten eine typisierte Fehlerhierarchie. Fangen Sie die Basisklasse Msv3ApiError fuer alle API-Fehler, oder spezifische Unterklassen fuer granulare Behandlung.

Msv3ApiError
├── Msv3BadRequestError        (400)
├── Msv3AuthError              (401)
├── Msv3NotFoundError          (404)
├── Msv3ProductUnavailableError (422)
├── Msv3RateLimitError         (429)  + .retry_after
├── Msv3WholesalerUnavailableError (502)
└── Msv3ServiceUnavailableError (503)

Debugging-Tipps

request_id mitliefern: Jede Antwort enthaelt eine request_id. Geben Sie diese bei Support-Anfragen an.
Zugangsdaten isoliert testen: Nutzen Sie POST /v1/connection/test, um Authentifizierungsprobleme separat zu pruefen.
Dry Run verwenden: Mit ?dry_run=true koennen Sie Bestellungen validieren, ohne sie tatsaechlich aufzugeben.
error_code pruefen: Der rohe MSV3-Code in error_code ordnet direkt dem internen Ablehnungsgrund des Grosshaendlers zu.

PharmaAutopilot