Grundlagen

Fehlerbehandlung

Fehlerformat, HTTP-Status, Fehlercodes und Retry-Verhalten.

Fehlerformat

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "The application request contains invalid or missing fields.",
    "details": [
      {
        "path": "vehicle.evb_number",
        "code": "required",
        "message": "An eVB number is required for this procedure."
      }
    ],
    "request_id": "req_b179e02d6458a31f74c9260e"
  }
}

Rate Limits verwenden gewichtete Einheiten

RateLimit-Limit und RateLimit-Remaining zählen Einheiten, nicht rohe HTTP-Requests. Das unternehmensweite Minutenbudget wird zusätzlich getrennt für Test- und Produktivumgebung geführt.

Operation	Kosten pro Aufruf
Produktiven oder Testantrag anlegen	`10` Einheiten
Testereignis auslösen	`5` Einheiten
Antrag, Dokumente oder Gebühren einschließlich Downloads abrufen	`3` Einheiten
Anträge auflisten	Angeforderter `limit`-Wert; Standard `20`, maximal `25` Einheiten

Retry-Matrix

HTTP	Bedeutung	Empfehlung
`400`	Ungültiges JSON oder Requestformat.	Client korrigieren; nicht unverändert wiederholen.
`401`	Schlüssel fehlt, ist ungültig oder widerrufen.	Konfiguration prüfen; nicht in Schleife wiederholen.
`403`	Recht oder Umgebung passt nicht.	Dashboard-Rechte beziehungsweise Schlüsselpräfix prüfen.
`404`	Ressource fehlt oder gehört zu anderem Konto.	IDs und Mandantenzuordnung prüfen.
`409`	Idempotenz- oder Zustandskonflikt.	Aktuelle Ressource lesen und Request prüfen.
`413`	Der JSON-Body überschreitet die zulässige Größe.	Payload verkleinern; nicht unverändert wiederholen.
`415`	Content-Type ist nicht `application/json`.	Header korrigieren; nicht unverändert wiederholen.
`422`	Request-Daten ungültig oder unvollständig.	Felder anhand `error.details` korrigieren.
`429`	Minutenbudget oder tägliches Testanlage-Budget erreicht.	`Retry-After` und bei Testanlagen `Test-Create-Reset` beachten.
`5xx`	Vorübergehender Serverfehler möglich.	Mit Backoff und demselben Idempotency-Key wiederholen.

Fehlercodekatalog

Der HTTP-Status bestimmt die Fehlerklasse; <code>error.code</code> enthält die konkrete Ursache.

HTTP	Fehlercodes	Bedeutung und nächste Aktion
`400`	`invalid_json`, `invalid_json_object`, `invalid_limit`, `invalid_cursor`, `idempotency_key_required`, `invalid_idempotency_key`	Requestformat, Pagination oder Idempotency-Key korrigieren.
`401`	`missing_api_key`, `invalid_api_key`, `revoked_api_key`, `expired_api_key`, `dashboard_account_inactive`	Bearer-Schlüssel und Dashboard-Zugang prüfen; nicht automatisch wiederholen.
`403`	`environment_mismatch`, `insufficient_scope`, `dashboard_application_not_allowed`	Passendes Schlüsselpräfix beziehungsweise den benötigten Scope verwenden und die Freigabe des Vorgangs im Dashboard prüfen.
`404`	`application_not_found`, `holder_not_found`, `holder_verification_not_found`, `signature_profile_not_found`, `license_plate_check_not_found`, `license_plate_reservation_not_found`, `license_plate_office_missing`, `order_not_found`, `document_not_found`, `fee_notice_not_found`, `route_not_found`	Nur kanonische IDs und Pfade verwenden; Konto- und Umgebungszuordnung prüfen.
`409`	`idempotency_key_conflict`, `idempotency_request_in_progress`, `holder_revision_conflict`, `license_plate_check_already_claimed`, `license_plate_reservation_conflict`, `documents_not_required`, `application_handoff_failed`, `invalid_test_state_transition`	Aktuelle Ressource lesen und doppelte Anlagen vermeiden.
`413`	`request_body_too_large`, `document_too_large`	Body beziehungsweise Upload unter die dokumentierte Größenbegrenzung bringen.
`415`	`unsupported_media_type`, `unsupported_document_type`	Für JSON-Endpunkte `application/json` verwenden; bei Uploads erlaubten MIME-Typ und automatische Multipart-Boundary senden.
`422`	`validation_failed`, `application_validation_failed`, `invalid_procedure`, `invalid_test_event`, `license_plate_wrong_district`, `license_plate_check_expired`, `license_plate_check_not_reservable`, `dashboard_context_incomplete`	Request-Daten, Bezirk, Checks oder Dashboard-Voraussetzungen korrigieren. Details können einen Feldpfad enthalten.
`422`	`holder_verification_required`, `holder_verification_incomplete`, `holder_verification_not_authorized`	Den Halter verifizieren, wenn Sie mit Vollmacht auf Digital-Zulassen einreichen. Mit eigenem KBA-Großkundenzugang entfällt die Verifizierung; bei AB gilt sie nie.
`429`	`rate_limit_exceeded`, `test_create_limit_exceeded`	`Retry-After` beachten. Beim Testanlage-Budget zeigen `Test-Create-Limit`, `Test-Create-Remaining` und `Test-Create-Reset` Grenze, Rest und Reset-Zeitpunkt.
`500`	`internal_error`, `application_persistence_failed`	Mit Backoff wiederholen. Bei einer Anlage denselben Body und Idempotency-Key verwenden.
`503`	`service_unavailable`, `idempotency_unavailable`, `application_handoff_failed`, `documents_preparation_failed`	Dienst vorübergehend nicht verfügbar; `Retry-After` beachten, sofern vorhanden, und Anlage mit demselben Idempotency-Key wiederholen.

Was ins Log gehört

request_id beziehungsweise X-Request-Id
HTTP-Methode und normalisierter Pfad ohne Signaturtoken
eigene externe Referenz und öffentliche Antrags-ID
HTTP-Status und Fehlercode
keine API-Schlüssel, Request-Bodies, Signaturlinks oder Binärdokumente