Fehlerbehandlung (Error Handling)

Die Partner-API verwendet Standard-HTTP-Statuscodes und gibt konsistente JSON-Fehlerantworten zurück.

Fehlerantwortformat

Alle Fehler folgen dieser Struktur:

{
	"statusCode": 400,
	"message": "Validation failed",
	"error": "Bad Request"
}

Statuscodes

Code	Fehler	Beschreibung
`400`	Bad Request	Ungültiger Anfragekörper, fehlende Pflichtfelder oder Validierungsfehler
`401`	Unauthorized	Fehlende, ungültige oder abgelaufene Authentifizierungsdaten
`403`	Forbidden	Gültige Zugangsdaten, aber unzureichende Berechtigungen für diese Aktion
`404`	Not Found	Die angeforderte Ressource existiert nicht
`409`	Conflict	Doppelte Anfrage erkannt (z. B. doppelter Idempotenzschlüssel mit unterschiedlichem Payload)
`429`	Too Many Requests	Ratenbegrenzung überschritten
`500`	Internal Server Error	Ein unerwarteter Fehler ist auf dem Server aufgetreten

Validierungsfehler

Bei 400-Fehlern, die durch Anfragevalidierung verursacht werden, kann das Feld message Details darüber enthalten, welche Felder die Validierung nicht bestanden haben:

{
	"statusCode": 400,
	"message": [
		"products.0.productId must be a UUID",
		"products.0.startAt must be a valid ISO 8601 date",
		"payment.type must be one of: CARD, GOOGLE_PAY, APPLE_PAY, IDEAL, REVOLUT, BANCONTACT"
	],
	"error": "Bad Request"
}

Best Practices

Überprüfen Sie immer das Feld statusCode, um die Fehlerkategorie zu bestimmen.
Bei 401-Fehlern überprüfen Sie Ihren API-Schlüssel, die Aktualität des Zeitstempels (innerhalb von 5 Minuten), die Eindeutigkeit des Nonce und die Signaturberechnung.
Bei 409-Fehlern bei der Bestellerstellung wurde die ursprüngliche Bestellung bereits verarbeitet. Rufen Sie sie über den Idempotenzschlüssel (Idempotency Key) oder die externe Referenz ab.
Bei 500-Fehlern versuchen Sie es mit exponentiellem Backoff erneut. Wenn der Fehler weiterhin besteht, kontaktieren Sie den Support.