Errors & status codes

Every Clearvo product returns the same HTTP status codes and a consistent 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.

HTTP errors

Clearvo uses standard HTTP status codes. Error responses include a JSON body (usually with ok: false).

An errors[] entry with UNKNOWN_FIELD_BUYER_RENAMED (POST /send body, stored as a rejection with HTTP 200) or UNKNOWN_HEADER_BUYER_RENAMED (bulk CSV header row) means the request still carries a retired buyer* input — see E-Invoicing for the current customer* field names.

Rate limits

Requests are counted against the API key that made them, in fixed 60-second windows, however many IP addresses the key is used from. Each endpoint class has its own budget, and sandbox and production keys are counted separately. The limits sit well above normal integration traffic — they exist to keep one runaway client from slowing everyone else down.

POST /query and GET /export have their own per-key budgets, documented on those endpoints, and are not counted above. When they are exceeded they return RATE_LIMITED (HTTP 429) rather than the RATE_LIMIT_EXCEEDED code used by the per-key limits in the table above. GET /health is unauthenticated and not counted.

Bulk rows budget

On top of the request count, bulk uploads are budgeted by size. The synchronous POST /send/bulk transport (uploads under 25MB) charges each CSV data row, and POST /receive/bulk charges each document, against 20,000 rows per minute per key. An upload larger than what remains of that budget in the current window is rejected whole with a 429 — nothing in it is processed — so split the file or wait for the window to reset. Uploads of 25MB or more to POST /send/bulk (up to 200MB) are stored and processed asynchronously and are not row-budgeted.

Response headers

Every counted response, success or error, tells you where you stand:

Handling a 429

A rate-limited request is not processed. Wait Retry-After seconds, then retry. If you send in bursts, spread the calls across the minute, or use the bulk endpoints instead of many single submits. Every rate-limited response has the same body:

{
  "ok": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded for this API key: 120 requests per minute on this endpoint class. Retry after 37 seconds.",
    "retryable": true
  },
  "hint": "You've exceeded the rate limit for this API key. Spread requests out, honour Retry-After, or contact support@clearvo.io for higher limits."
}

A separate network-level protection against abusive traffic also exists, set well above the per-key limits. It returns the same body with X-RateLimit-Scope: ip; a legitimate integration will not encounter it. If your integration genuinely needs higher limits, contact support@clearvo.io.

Error object

Most error responses include ok: false and an error object with code and message, plus an optional hint. Two envelope shapes exist, so read defensively:

• { "ok": false, "error": { "code", "message", "retryable" }, "hint" } — the shape described below.
• { "error": "message string", "hint": "…" } — a bare string in error, used by several endpoints (for example GET /invoices, the upload endpoints and the invoice action endpoints). Some of these add a sibling code field (for example "code": "DUPLICATE_INVOICE_NUMBER" or "FILE_TOO_LARGE"); POST /send can return either shape depending on the failure.

If error is a string, use the top-level code when present, otherwise the HTTP status.

A specific endpoint may add its own fields on top of this base envelope — e.g. violations[] on a structural validation failure, or source/detail on an authority clearance rejection (both shown below).

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body validation failed",
    "violations": [
      { "field": "lines[0].taxRate", "message": "taxRate is required and must be a number between 0 and 100" }
    ]
  }
}

{
  "status": "REJECTED",
  "reason": "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"
  }
}

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