Error Reference

Errors & status codes

Every Clearvo product returns the same HTTP status codes and the same JSON error envelope. Product-specific rejection reasons — e.g. e-invoicing authority clearance codes — are documented on each product's own page and linked from here.

Error Reference

HTTP errors

Clearvo uses standard HTTP status codes. All error responses include a JSON body with ok: false.

Status	Meaning	Common cause
401	Unauthorized	Missing or invalid `x-api-key`. Check the header name (lowercase) and that the key is active.
400	Bad Request	Payload validation failed. The response includes `field` and `message` for each violation.
403	Forbidden	The key is valid but not authorized for this entity or product — e.g. an entity-scoped key used against a different entity, or a read-only key on a write operation.
409	Conflict	Idempotency conflict — a different payload was submitted with the same `x-idempotency-key`. Generate a new key.
422	Unprocessable Entity	Country- or product-specific validation failure (e.g. missing buyer `taxId` for reverse charge, invalid Italian Partita IVA check digit).
500	Internal Server Error	Unexpected Clearvo error. The response includes a `requestId` — include this when contacting support.

ℹ

E-Invoicing has an additional error class that isn't an HTTP error: POST /invoices returns 200 even when an authority later rejects the invoice. See Clearance errors.

Error Reference

Error object

All error responses — both HTTP errors and authority rejections — return a consistent error envelope.

JSON — HTTP error (400)

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body validation failed",
    "violations": [
      { "field": "lines[0].taxCode", "message": "must be a valid EN16931 tax code" }
    ]
  }
}

JSON — Clearance rejection (from status poll)

{
  "clearanceStatus": "REJECTED",
  "terminal": true,
  "rejectedAt": "2024-01-15T10:47:12Z",
  "error": {
    "source": "SDI",
    "code": "00102",
    "message": "Partita IVA fornitore non trovata",
    "detail": "Supplier tax ID 01234567890 is not registered with the Italian Revenue Agency"
  }
}

JSON — Internal error (500)

{
  "ok": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred",
    "requestId": "req_01J9XKZ4MFBVQH7PRTD8CNWY5"
  }
}