API Fehler

Verwenden Sie HTTP-Statuscodes, um zu entscheiden, ob Sie die Anfrage korrigieren, Zugangsdaten erneuern oder später erneut versuchen sollten.

Status	Bedeutung	Typische Behandlung
400	Request-Payload ist ungültig.	Request Body oder Optionen korrigieren.
401	API-Key fehlt, ist ungültig oder wurde widerrufen.	Ein gültiges Token bereitstellen.
403	Token hat keinen Zugriff.	Konto- und Tokenberechtigungen prüfen.
404	Operation oder PDF wurde nicht gefunden.	Operation ID oder Idempotency Key prüfen.
409	Idempotency-Key-Konflikt oder PDF wurde angefordert, bevor es verfügbar ist.	Für denselben Key denselben Payload verwenden, neuen Key wählen oder auf Abschluss warten.
429	Zu viele Integrationsrequests in kurzer Zeit.	Warten und später erneut versuchen.
500	Unerwarteter Serverfehler.	Später erneut versuchen; Support kontaktieren, wenn der Fehler bestehen bleibt.

Laufende asynchrone Antworten enthalten Retry-After. Verwenden Sie diesen Wert statt aggressiv zu pollen.

Form Der Fehlerantwort

Die meisten API-Fehler geben application/problem+json zurück:

{
  "title": "Request validation failed",
  "status": 400,
  "detail": "The request body is invalid."
}

Verwenden Sie den HTTP-Statuscode für automatisierte Behandlung. Verwenden Sie detail für Logs und Diagnose, aber bauen Sie keine Clientlogik, die von exaktem Wortlaut abhängt.

Retry-Hinweise

Wiederholen Sie nur, wenn der Fehler temporär ist:

• Wiederholen Sie 429 nach einer Wartezeit.
• Wiederholen Sie 500 und Netzwerk-Timeouts mit Backoff.
• Pollen Sie asynchrone Running-Operationen mit dem Response-Header Retry-After.

Wiederholen Sie 400, 401, 403 oder 409 nicht automatisch, ohne Request, Token, Berechtigungen oder Idempotency-Key-Nutzung zu ändern.