---
title: "Errors"
description: "Every error code returned by the Flowie Exchange API, with the cause and the remediation."
canonical: "https://docs.get-flowie.com/reference/errors"
source: "https://docs.get-flowie.com/reference/errors.html"
---

# Errors

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:
[code] 
    {
      "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.get-flowie.com/errors#INVALID_REQUEST"
      }
    }
[/code]

`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](<index.html>).  
`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](<index.html#create-api-key>).  
`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](<index.html#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](<index.html#search-directory>).  
`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](<https://status.flowie.ink>).  
`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](<../compliance/be.html#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](<https://docs.peppol.eu/poacc/billing/3.0/rules/>).