Fehler und Regelcodes

Jeder Fehler ist ein RFC-9457-Problem (application/problem+json) mit einem stabilen code, nach dem Sie unterscheiden können:

{
  "type": "about:blank",
  "title": "Unprocessable Content",
  "status": 422,
  "code": "invoice.invalid",
  "detail": "The invoice violates 2 rules",
  "instance": "/v1/invoices",
  "findings": [
    {
      "ruleId": "BR-DE-15",
      "severity": "ERROR",
      "location": "buyerReference",
      "message": { "de": "Käuferreferenz (Leitweg-ID) fehlt", "en": "…" },
      "source": "…"
    }
  ]
}

detail ist englisch und kann sich ändern; code nicht.

Häufige Codes

• 400 request.*: fehlerhaftes JSON oder Parameter (request.unreadable, request.invalid mit errors, request.invalid-parameter, request.invalid-format).
• 404 request.not-found (kein solcher Endpunkt), 405 request.method-not-allowed, 406 request.not-acceptable, 415 request.unsupported-media-type, 413 request.too-large, 408 request.too-slow.
• 500 server.error: ein unerwarteter Fehler bei uns; später erneut versuchen und uns Bescheid geben, wenn er bleibt.
• 401 auth.invalid-api-key, 403 auth.insufficient-scope, 403 sandbox.live-only (Testschlüssel außerhalb der Sandbox).
• 404 invoice.not-found, seller.not-found, delivery.not-found, document.not-found.
• 409 invoice.duplicate-number, idempotency.conflict, delivery.duplicate, api-key.limit, sandbox.limit.
• 402 plan.document-limit, plan.seller-limit, plan.country-not-included, plan.feature-not-included, billing.read-only, plan.trial-ended.
• 403 seller.not-verified: E-Mail und echtes Peppol brauchen einen verifizierten Verkäufer.
• 413 document.too-large, 415 document.unsupported-type, 422 document.unreadable (eingehende Dateien).
• 422 invoice.invalid (mit findings), idempotency.key-reused, invoice.too-large.
• Webhooks: 400 webhook.unknown-event, 404 webhook.not-found, 404 webhook.delivery-not-found, 409 webhook.removed, 409 webhook.delivery-pending, 409 webhook.limit, 429 webhook.too-many.
• 429 rate-limit.exceeded, rate-limit.concurrency, tenant.heavy-work-running, delivery.email-limit.
• 503 invoice.busy, inbound.busy, sandbox.busy: nach Retry-After Sekunden wiederholen.

Regelcodes in Befunden

ruleId nennt die verletzte Regel:

• BR-…, BR-CO-…, BR-S-…: Geschäftsregeln der EN 16931.
• BR-DE-…: XRechnung (CIUS Deutschland), z. B. BR-DE-15 Leitweg-ID fehlt.
• BR-RO-…: CIUS-RO für Rumänien.
• Schema- und Schematron-Befunde des offiziellen KoSIT-Prüftools mit der ursprünglichen Regel-ID.

Befunde mit severity ERROR verhindern das Ausstellen; WARNING und INFO nicht. Prüfen Sie zuerst mit POST /invoices/validate, um alle Befunde zu sehen, ohne etwas zu speichern.