Błędy

API używa standardowych kodów statusu HTTP oraz spójnej koperty błędu. Każdy błąd zawiera stabilny, czytelny maszynowo message (kod błędu) oraz, gdy ma to znaczenie, szczegóły w errors.

Struktura błędu#

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

Zawsze podejmuj decyzje na podstawie message (kodu), a nie czytelnego dla człowieka tekstu. Tekst może się zmienić, kod nie. Pole errors ma dwie postacie: przy walidacji pól to lista obiektów { field, code?, message }, w pozostałych przypadkach lista zdań wyjaśniających, np. ["REST API wymaga planu MAX."].

Kody statusu#

Kody błędów#

Pełna tabela kodów ze statusami jest też na górze specyfikacji OpenAPI (info.description).

Nagłówki odpowiedzi#

Każda odpowiedź niesie nagłówek X-Request-ID z unikalnym identyfikatorem żądania. Zapisuj go w logach integracji i podawaj w zgłoszeniach do pomocy: pozwala odnaleźć konkretne wywołanie po stronie Fakturnii. Nagłówki X-RateLimit-* i Retry-After opisuje strona Limity zapytań, a Idempotent-Replayed strona Idempotentność.

Obsługa błędów#

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 ?? [])}`);
  }
}

Błędy 5xx i 429 można bezpiecznie ponawiać z odczekiwaniem (backoff) wtedy, gdy żądanie zawierało Idempotency-Key. Zobacz Idempotentność.