Skip to content
Fakturnaut
Sign up free

Errors and rule codes

Every error is an RFC 9457 problem (application/problem+json) with a stable code you can switch on:

{
  "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": "…", "en": "Buyer reference (Leitweg-ID) is missing" },
      "source": "…"
    }
  ]
}

detail is English and may change; code does not.

Common codes

  • 400 request.*: malformed JSON or parameters (request.unreadable, request.invalid with errors, request.invalid-parameter, request.invalid-format).
  • 404 request.not-found (no such endpoint), 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: an unexpected failure on our side; retry later and tell us if it persists.
  • 401 auth.invalid-api-key, 403 auth.insufficient-scope, 403 sandbox.live-only (a test key outside the 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 and real Peppol need a verified seller.
  • 413 document.too-large, 415 document.unsupported-type, 422 document.unreadable (inbound files).
  • 422 invoice.invalid (with 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: retry after Retry-After seconds.

Rule codes in findings

ruleId names the rule that failed:

  • BR-…, BR-CO-…, BR-S-…: EN 16931 business rules.
  • BR-DE-…: XRechnung (CIUS Germany), e.g. BR-DE-15 Leitweg-ID missing.
  • BR-RO-…: CIUS-RO for Romania.
  • Schema and Schematron findings from the official KoSIT validator, with the original rule id.

Findings with severity ERROR block issuing; WARNING and INFO do not. Validate first with POST /invoices/validate to see all findings without storing anything.