Errors

The API uses standard HTTP status codes and a consistent error envelope. Every error carries a stable, machine-readable message (the error code) and, where it matters, details in errors.

Error shape#

{
  "success": false,
  "data": null,
  "message": "AMBIGUOUS_PARTY",
  "executionTime": 5,
  "errors": ["Podaj albo buyerId, albo buyer, ale nie oba."]
}

Always branch on message (the code), never on the human-readable text. The text may change, the code will not. errors has two shapes: for field validation it is a list of { field, code?, message } objects, otherwise a list of explanatory sentences, e.g. ["REST API wymaga planu MAX."].

Status codes#

Error codes#

The full table of codes with statuses is also at the top of the OpenAPI specification (info.description).

Response headers#

Every response carries an X-Request-ID header with a unique request id. Log it in your integration and quote it in support requests: it lets Fakturnia find that exact call. The X-RateLimit-* and Retry-After headers are described in Rate limits, Idempotent-Replayed in Idempotency.

Handling errors#

const res = await fetch(url, opts);
const body = await res.json();

if (!body.success) {
  switch (body.message) {
    case 'TOKEN_EXPIRED':           // refresh the token and retry once
    case 'UNAUTHORIZED':            // re-authenticate; a revoked API account needs a new one
    case 'SUBSCRIPTION_REQUIRED':   // the account needs the MAX plan; tell the user, do not retry
    case 'RATE_LIMIT_EXCEEDED':     // wait Retry-After seconds, then retry
    case 'DOCUMENT_NUMBER_EXISTS':  // pick a new number or let the API auto-number
    case 'VALIDATION_ERROR':        // 400 or 422: inspect body.errors
    default:
      throw new Error(`${body.message} [${res.headers.get('X-Request-ID')}]: ${JSON.stringify(body.errors ?? [])}`);
  }
}

5xx and 429 errors are safe to retry with a backoff when the request carried an Idempotency-Key. See Idempotency.