Error Catalog

Every error, with a fix

If you see one of these codes, jump to the row. Every entry includes the typical cause and the exact remediation.

The error envelope

All errors — whether from Flowie itself or relayed from an upstream (Peppol SMP, PPF, SDI) — share this shape:

{
  "error": {
    "type":    "validation_error",      // coarse category
    "code":    "INVALID_REQUEST",       // stable machine code
    "message": "Request validation failed",
    "details": [                         // optional, field-level
      { "field": "document.lines[0].vatRate",
        "rule":  "range",
        "message":"Must be between 0 and 100" }
    ],
    "requestId": "req_01HXYZ2K3M4N5P6Q7R",
    "docUrl":    "https://docs.flowie.ink/errors#INVALID_REQUEST"
  }
}

requestId is always present — include it in every support ticket.

400 · Validation errors

Code	Cause	Fix
`INVALID_REQUEST`	One or more fields failed schema validation.	Inspect `details[]`; each entry names the offending `field` and `rule`.
`MISSING_FIELD`	A required field is absent.	Supply the field. Required fields are marked in the API reference.
`INVALID_ENUM`	Value isn't in the allowed set.	Use one of the listed enum values — don't assume case-insensitivity.
`INVALID_VAT_FORMAT`	Pattern `^[A-Z]{2}[A-Z0-9]+$` failed.	Strip spaces, uppercase, include country prefix.
`INVALID_IBAN`	IBAN checksum failed.	Re-check the IBAN against `mod-97`.
`INVALID_CURRENCY`	Not an ISO 4217 code.	Use 3-letter uppercase codes (`EUR`, `USD`…).
`INVALID_DATE`	Not ISO 8601.	Format as `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SSZ`.

401 / 403 · Authentication & authorization

Code	Cause	Fix
`MISSING_AUTH`	No `Authorization` header.	Add `Authorization: Bearer …`.
`INVALID_TOKEN`	JWT couldn't be verified against our JWKS.	Fetch a fresh token. Check the audience claim matches `https://api.flowie.ink/`.
`EXPIRED_TOKEN`	JWT past its `exp`.	Refresh and retry.
`REVOKED_KEY`	API key was deleted.	Issue a new key via POST /v1/api-keys.
`INSUFFICIENT_SCOPE`	Key is valid but lacks the required scope.	Re-issue the key with the missing scope or switch to a broader key.
`COMPANY_FORBIDDEN`	The key is scoped to a different company.	Use the right key, or add `X-Flowie-Company` on a platform key.

404 · Not found

Code	Cause	Fix
`RESOURCE_NOT_FOUND`	Generic 404.	Check the ID — IDs are case-sensitive.
`COMPANY_NOT_FOUND`	No company with this id / VAT / Peppol ID in your org.	If you used `vat:` or `peppol:` prefix, double-check the scheme.
`DOCUMENT_NOT_FOUND`	Document doesn't exist or is outside your visibility.	Platform keys see tenant docs only when acting on behalf of that tenant (`X-Flowie-Company`).

409 · Conflict

Code	Cause	Fix
`COMPANY_EXISTS`	VAT already registered by your organization.	Treat as an idempotent upsert — use `existingId` from the error payload.
`IDEMPOTENCY_IN_PROGRESS`	A request with the same key is still processing.	Wait a moment and retry.
`IDEMPOTENCY_BODY_MISMATCH`	Same key, different body.	Either reuse the exact original body or use a new key.
`INVALID_TRANSITION`	Lifecycle status change isn't allowed from the current state.	See `allowedTransitions` returned by GET lifecycle.

422 · Semantic errors

Code	Cause	Fix
`VAT_NOT_FOUND`	VAT doesn't exist in the national registry.	Double-check the VAT; registries lag by a few days for new entities.
`VAT_INACTIVE`	VAT is flagged inactive (ceased activity).	Confirm with the customer.
`RECIPIENT_NOT_FOUND`	Peppol ID isn't registered anywhere.	Ask the customer for a valid Peppol ID or use directory search.
`RECIPIENT_CANNOT_RECEIVE`	Peppol ID exists but doesn't accept this document type.	Check `documentTypes` on the directory record. Ask the recipient's AP to extend SMP.
`UBL_VALIDATION_FAILED`	Rendered UBL failed Peppol BIS schematron.	See Peppol BIS rule codes below (`BR-`, `BR-CO-`).

429 · Rate limit

Code	Cause	Fix
`RATE_LIMITED`	You exceeded req/min.	Sleep `Retry-After` seconds, then retry. Parallelize fewer calls, or upgrade plan.
`QUOTA_EXCEEDED`	Monthly document quota is used up.	Upgrade plan, or wait for the monthly reset.

5xx · Server errors

Code	Cause	Fix
`INTERNAL_ERROR`	Unexpected server error.	Retry with exponential backoff. Persist → report `requestId` to support.
`UPSTREAM_UNAVAILABLE`	A dependency (SMP, PPF…) is down. Circuit breaker is open.	Retry after `Retry-After`. Check status page.
`UPSTREAM_TIMEOUT`	Dependency took too long.	Safe to retry — request is idempotent when you pass `Idempotency-Key`.

Delivery failures

These come after a document.sent event, as a document.failed webhook. The document stays sendable — fix and re-send with a new number.

Code	Cause	Fix
`AP_REJECTED`	Recipient's access point rejected the payload.	Read `errorMessage` — often a schema or buyer-reference issue.
`TRANSPORT_FAILURE`	Temporary AS4 transport failure.	Retry automatically — Flowie re-sends up to 5 times.
`SBDH_ERROR`	Standard Business Document Header malformed.	Internal; should not surface. Contact support.

Compliance failures

Relayed from PPF (FR) or SDI (IT). Surfaced via compliance.reported webhook with status: "failed". Belgium has no regulator-side report; BE-CIUS validation errors surface as BR-BE-* on the synchronous send response — see Belgium · error codes.

Platform	Code	Meaning
PPF (FR)	`00025`	Invoice number doesn't match PPF format.
PPF (FR)	`00058`	Service Executant missing for public buyer.
SDI (IT)	`00200`	Schema validation error.
SDI (IT)	`00306`	Codice Destinatario unknown.

Peppol BIS rule codes (selected)

Rule	Summary
`BR-01`	An Invoice shall have a Specification identifier.
`BR-02`	An Invoice shall have an Invoice number.
`BR-16`	An Invoice shall have at least one Invoice line.
`BR-CL-04`	Invoice currency code shall be from ISO 4217.
`BR-CO-10`	Sum of line net amounts equals net amount.
`BR-CO-15`	Invoice total with VAT = net + VAT.
`BR-DEC-12`	Decimals limited to 2 on monetary totals.

Full list: Peppol BIS 3.0 rules.