Fehler & Limits
Fehler richtig einordnen, Limits beachten und Integrationsprobleme beheben.
Auf dieser Seite
Fehlerantworten
API-Fehler verwenden application/problem+json mit code, detail und requestId. Bewahren Sie die Request-ID für die Diagnose auf. Der SDK stellt sie über RebilixApiException bereit.
| HTTP | Vorgehen |
|---|---|
| 400 / 415 / 422 | Schema, Medientyp, Pflichtfelder oder fachliche Befunde prüfen. |
| 401 / 403 | Schlüssel, Ablauf, Umgebung und aktuelle Berechtigungen des Erstellers prüfen. |
| 404 | Ressourcen-ID, Arbeitsbereich, Umgebung und Verfügbarkeit des Artefakts kontrollieren. |
| 409 | Fehlercode unterscheiden: abweichende Idempotenzdaten, laufende Verarbeitung, geänderte Prüfung oder veralteter Retry-Zähler. |
| 408 / 413 | Upload-Zeitlimit bzw. Dateigröße prüfen. |
| 429 / 503 | Retry-After beachten, dieselben Daten mit demselben Idempotency-Key erneut senden. |
Größen- und Verarbeitungslimits
| Grenze | Wert |
|---|---|
| JSON / XML / PDF | 1 MiB / 2.000.000 Bytes / 10 MiB |
| Upload-Zeitlimit | 30 Sekunden; HTTP-Client für synchrone PDF-Verarbeitung auf mindestens fünf Minuten einstellen. |
| Je Schlüssel und Minute | 60 Anfragen / 5 Verarbeitungs-POSTs |
| Je Arbeitsbereich / Umgebung / Minute | 300 Anfragen / 20 Verarbeitungs-POSTs |
| Parallelität | Höchstens zwei API-Verarbeitungen je Arbeitsbereich/Umgebung, vier je Prozess. Hintergrundworker zusätzlich eine je Arbeitsbereich/Umgebung. |
| Offene Hintergrundaufträge | 50 je Arbeitsbereich/Umgebung |
| Verbindungs-IP | 120 Anfragen pro Minute und Instanz. Hinter einem Proxy kann dieses Limit geteilt sein. |
| Verlauf / Retry-JSON | Bis zu 100 Einträge je API-Seite / 1 KiB Retry-Anfrage |
Idempotenz und sichere Wiederholung
Dokumentverarbeitung und Jobannahme verlangen Idempotency-Key: 16–128 druckbare ASCII-Zeichen ohne Leerzeichen, zum Beispiel eine UUID. Speichern Sie ihn mit Ihrem ERP-Vorgang.
Gleiche Aktion, gleicher normalisierter Medientyp und exakt gleiche Bytes liefern das gespeicherte Ergebnis. Idempotent-Replayed: true zeigt die Wiederholung. Geänderte Daten mit demselben Schlüssel ergeben 409 idempotency_conflict. Ein neuer Schlüssel startet bewusst einen neuen Vorgang.
Bei 409 request_in_progress warten Sie gemäß Retry-After. Nach Prozessabbruch kann eine synchrone Reservierung bis zu zehn Minuten gesperrt bleiben. Job-Leases laufen nach 15 Minuten ab; Webhook-Leases nach zwei Minuten. Worker müssen laufen, damit Wiederaufnahme erfolgen kann.
/jobs/{id}/retry und /webhook-deliveries/{id}/retry verwenden expectedAttempts statt eines Idempotency-Keys. Bei 409 neu laden und eine erneute Wiederholung ausdrücklich entscheiden.
Webhook-Probleme eingrenzen
| Symptom | Prüfen |
|---|---|
| Keine HTTP-Anfrage | CaptureOnly? Worker aktiv? Empfänger vor Jobabschluss angelegt? Richtige Umgebung? Auftrag bereits terminal? |
| 401 beim ERP | Exaktes Geheimnis einschließlich whsec_, Originalbytes, vollständige Header und synchronisierte Uhr. |
| unsafe_destination | Öffentlicher Host; alle aufgelösten IPs müssen zulässig sein. Keine privaten Adressen oder Redirects. |
| endpoint_inactive | Empfänger deaktiviert oder Ersteller nicht mehr berechtigt. Unter einem berechtigten Konto Ersatz anlegen. |
| signing_key_unavailable | Rebilix-Betreiber muss den passenden Data-Protection-Schlüsselbund wiederherstellen. |
| ERP erhält Duplikate | Erwartbar bei Wiederholungen. Eindeutige Ereignis-ID und transaktionale Inbox verwenden. |
| 2xx, aber ERP bleibt unverändert | ERP-Inbox und eigenen Worker prüfen. 2xx bestätigt Empfang, nicht Abschluss der ERP-Verarbeitung. |
Prüfen Sie den Zustellverlauf in der App oder GET /webhook-deliveries/{id}. Payload, HTTP-Status und Signatur-Header jedes Versuchs helfen bei der Zuordnung.
Monatliche Arbeitsbereichskontingente
HTTP 429 mit workspace_allowance_exceeded bedeutet, dass das monatliche Kontingent für diese Aktion und Umgebung erreicht ist. Unter Nutzung & Tarif können Inhaber und Administratoren Verbrauch und verbleibende Einheiten prüfen. Diese Grenze gilt zusätzlich zu den kurzfristigen API-Ratenlimits.
Nicht sofort in einer Schleife wiederholen: Nach Kontingenterhöhung oder Monatswechsel dieselbe Anfrage mit demselben Idempotency-Key erneut senden. Hintergrundaufträge prüfen das Kontingent bei Annahme und bei Verarbeitung; 202 reserviert keine Monatseinheit. Bei erschöpftem Kontingent bleibt der Auftrag für eine ausdrückliche Wiederholung erhalten.
Erfolgreich gespeicherte Ergebnisse werden einmal gezählt, auch bei ungültigem Prüfergebnis oder gesperrter Konvertierungsprüfung. Technische Fehler ohne Ergebnis zählen nicht. Erzeugung und Konvertierungsprüfung enthalten ihre internen Prüfungen. Konvertierungsbestätigung, Downloads, idempotente Wiederholungen und Webhook-Zustellungen zählen nicht erneut. Live und Sandbox sind getrennt. Reservierungen sind zehn Minuten gültig; der Monat wird bei Reservierung in Europe/Berlin festgelegt. Bereits zugelassene Vorgänge können innerhalb ihrer Reservierung nach einem Tarifwechsel fertiggestellt werden.