Developers
OpenAPI ↗
Zur App
Dokumentation / Referenz
API v1 · Referenz

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.

HTTPVorgehen
400 / 415 / 422Schema, Medientyp, Pflichtfelder oder fachliche Befunde prüfen.
401 / 403Schlüssel, Ablauf, Umgebung und aktuelle Berechtigungen des Erstellers prüfen.
404Ressourcen-ID, Arbeitsbereich, Umgebung und Verfügbarkeit des Artefakts kontrollieren.
409Fehlercode unterscheiden: abweichende Idempotenzdaten, laufende Verarbeitung, geänderte Prüfung oder veralteter Retry-Zähler.
408 / 413Upload-Zeitlimit bzw. Dateigröße prüfen.
429 / 503Retry-After beachten, dieselben Daten mit demselben Idempotency-Key erneut senden.

Größen- und Verarbeitungslimits

GrenzeWert
JSON / XML / PDF1 MiB / 2.000.000 Bytes / 10 MiB
Upload-Zeitlimit30 Sekunden; HTTP-Client für synchrone PDF-Verarbeitung auf mindestens fünf Minuten einstellen.
Je Schlüssel und Minute60 Anfragen / 5 Verarbeitungs-POSTs
Je Arbeitsbereich / Umgebung / Minute300 Anfragen / 20 Verarbeitungs-POSTs
ParallelitätHöchstens zwei API-Verarbeitungen je Arbeitsbereich/Umgebung, vier je Prozess. Hintergrundworker zusätzlich eine je Arbeitsbereich/Umgebung.
Offene Hintergrundaufträge50 je Arbeitsbereich/Umgebung
Verbindungs-IP120 Anfragen pro Minute und Instanz. Hinter einem Proxy kann dieses Limit geteilt sein.
Verlauf / Retry-JSONBis 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.

Retry-Endpunkte sind eine bewusste Ausnahme.

/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

SymptomPrüfen
Keine HTTP-AnfrageCaptureOnly? Worker aktiv? Empfänger vor Jobabschluss angelegt? Richtige Umgebung? Auftrag bereits terminal?
401 beim ERPExaktes 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_inactiveEmpfänger deaktiviert oder Ersteller nicht mehr berechtigt. Unter einem berechtigten Konto Ersatz anlegen.
signing_key_unavailableRebilix-Betreiber muss den passenden Data-Protection-Schlüsselbund wiederherstellen.
ERP erhält DuplikateErwartbar bei Wiederholungen. Eindeutige Ereignis-ID und transaktionale Inbox verwenden.
2xx, aber ERP bleibt unverändertERP-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.

Verbindung wird wiederhergestellt …

Neuer Verbindungsversuch in Sekunden.

Die Verbindung konnte nicht wiederhergestellt werden.
Bitte versuchen Sie es erneut oder laden Sie die Seite neu.

Ihre Sitzung wurde pausiert.

Die Sitzung konnte nicht fortgesetzt werden.
Bitte versuchen Sie es erneut oder laden Sie die Seite neu.