Fehlercodes

`error.code`	HTTP	Typische Ursache	Empfohlene Maßnahme
`unauthorized`	401	Fehlender/ungültiger API-Schlüssel oder Schlüssel aus einer anderen Umgebung	Senden Sie den Schlüssel im Header `X-B2B-API-Key` und stellen Sie sicher, dass er zur richtigen Umgebung passt (Sandbox, Staging oder Produktion).
`missing_api_key`	401	Der API-Schlüssel wurde nicht im Header übermittelt	Senden Sie den Schlüssel im Header `X-B2B-API-Key` und stellen Sie sicher, dass er zur richtigen Umgebung passt (Sandbox, Staging oder Produktion).
`invalid_api_key`	401	Der angegebene API-Schlüssel ist ungültig	Verwenden Sie einen gültigen API-Schlüssel im Header `X-B2B-API-Key` und stellen Sie sicher, dass er zur richtigen Umgebung passt.
`expired_api_key`	401	Der angegebene API-Schlüssel ist abgelaufen	Verwenden Sie einen gültigen und aktiven API-Schlüssel im Header `X-B2B-API-Key`.
`no_account_group`	403	Gültiger Schlüssel, aber keine Gruppe/Berechtigungen damit verknüpft	Lassen Sie Berechtigungen für diesen Schlüssel aktivieren oder zuweisen (Staging-Konten benötigen ein Support-Ticket; Sandbox-Berechtigungen werden automatisch vergeben).
`resource_missing`	404	Die Ressourcen-ID existiert nicht oder ist in Ihrem Tenant nicht zugänglich	Überprüfen Sie den Endpoint und die verwendete ID.
`invalid_request_params`	400	Fehlerhaftes JSON, falsche Datentypen oder unerwartete Struktur	Validieren Sie die Payload vor dem Senden.
`invalid_api_version` ¹	400	API-Version `{api_version}` wird nicht unterstützt	Verwenden Sie eine unterstützte API-Version im Header `X-B2B-API-Version`.
`missing_api_version` ¹	400	API-Version wurde weder im Header noch in der Integration Group angegeben	Senden Sie den Header `X-B2B-API-Version` mit einer unterstützten Version.
`api_version_subdomain_mismatch` ¹	400	Die Subdomain stimmt nicht mit der im Header angegebenen oder dem API-Schlüssel zugeordneten API-Version überein	Verwenden Sie die korrekte Subdomain. Nutzen Sie `app.b2brouter` oder `app-staging.b2brouter` für die Legacy-Version (`v2025-01-01`). Verwenden Sie `api.b2brouter` oder `api-staging.b2brouter` für Versionen ab `v2025-10-13`.
`parameter_blank`, `parameter_empty`	422	Pflichtfelder fehlen oder sind leer	Ergänzen Sie die erforderlichen Felder und senden Sie die Anfrage erneut.
`parameter_inclusion`	422	Wert nicht im erlaubten Katalog enthalten (zum Beispiel ein ungültiges `scheme`)	Prüfen Sie die erlaubten Werte (siehe Schemes Guide oder API-Listen) und korrigieren Sie den Wert.
`parameter_taken`	422	Ein eindeutiger Wert existiert bereits (zum Beispiel Rechnungsnummer)	Verwenden Sie einen neuen Wert oder führen Sie zuerst eine GET-Anfrage aus, um Duplikate zu vermeiden.
`parameter_cannot_change`	422	Versuch, ein unveränderbares Feld zu bearbeiten	Entfernen Sie das Feld aus der Aktualisierung oder erstellen Sie eine neue Ressource.
`conflict`	409	Der aktuelle Ressourcenstatus verhindert die Operation	Beheben Sie den Konflikt und versuchen Sie die Anfrage erneut.
(kein Code)	429	Das Rate Limit wurde überschritten	Implementieren Sie exponentielles Backoff, verwenden Sie Caching und bevorzugen Sie Webhooks statt Polling.

Schnelle Beispiele

1) 401 Unauthorized (falscher oder fehlender API-Schlüssel)

Beispielanfrage

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts?offset=0&limit=25' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Beispielantwort

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API Key provided, or the API key might not have the necessary permissions for this action.",
    "type": "invalid_request_error"
  }
}

Stellen Sie sicher, dass Sie den richtigen API-Schlüssel für Ihre Umgebung verwenden (Sandbox test_…, Staging oder Produktion) und ihn im Header X-B2B-API-Key senden.

2) 404 Not Found (Ressource existiert nicht oder ist nicht zugänglich)

Beispielanfrage

curl --request GET \
  --url https://api-staging.b2brouter.net/directory/es/ES1234567890 \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Beispielantwort

{
  "error": "Not found"
}

3) 422 Unprocessable Entity (Validierungsfehler)

Beispielanfrage

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/transports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json'

Beispielantwort

{
  "error": {
    "code": "parameter_taken",
    "message": "Transport type code has already been taken and Peppol Endpoint ID has already been taken",
    "param": "transport_type_code",
    "request_log_url": "https://api-staging.b2brouter.net/api_requests/123456",
    "type": "invalid_request_error"
  }
}

Validierungsfehler liefern HTTP 422 (Unprocessable Entity) mit feldbezogenen Fehlerdetails zurück, sodass Sie die Eingabedaten korrigieren und die Anfrage erneut senden können.

Request-Tracing

Jede protokollierte API-Antwort enthält den Header X-B2B-API-Request-Id mit der eindeutigen Kennung des gespeicherten Request-Logs.

Sie können diesen Wert verwenden, um:

Eine Antwort mit dem serverseitigen Logeintrag zu verknüpfen.
Ihn in Support-Tickets für schnellere Untersuchungen anzugeben.
Ihn in Ihren eigenen Anwendungslogs für End-to-End-Tracking zu speichern.

Fehlerantworten können außerdem ein Feld request_log_url im JSON-Body enthalten, das direkt auf das Request-Log verweist.

Best Practices für die Fehlerbehandlung

Authentifizierung: Verwenden Sie separate API-Schlüssel pro Umgebung und senden Sie immer X-B2B-API-Key.
Rate Limiting: Nutzen Sie exponentielles Backoff, cachen Sie Antworten und bevorzugen Sie nach Möglichkeit Webhooks statt Polling.
Kontrollierte Werte: Wenn ein Wert aus einem Katalog stammen muss (zum Beispiel scheme), prüfen Sie zuerst die Schemes-API oder den entsprechenden Guide.