Błędy i limity

Format odpowiedzi błędu

Wszystkie błędy zwracane są jako JSON o jednolitej strukturze:

{
  "error": "insufficient_scope",
  "message": "Token nie posiada wymaganego uprawnienia",
  "timestamp": "2025-01-15T14:30:00Z",
  "path": "/api/PurchaseDocuments/my",
  "requestId": "req_abc123def456"
}

Pole	Opis
`error`	Kod błędu (maszynowy identyfikator)
`message`	Opis czytelny dla człowieka
`timestamp`	Czas wystąpienia błędu (ISO 8601)
`path`	Ścieżka endpointu, który zwrócił błąd
`requestId`	Unikalny identyfikator zapytania (przydatny przy kontakcie z supportem)

Kody statusów HTTP

Kod	Znaczenie	Opis
`200`	OK	Zapytanie zakończone sukcesem
`204`	No Content	Brak treści (np. dokument w trakcie przetwarzania)
`401`	Unauthorized	Brak tokenu, token nieprawidłowy lub wygasły
`403`	Forbidden	Token nie posiada wymaganego uprawnienia (scope)
`404`	Not Found	Zasób nie istnieje
`429`	Too Many Requests	Przekroczono limit zapytań
`500`	Internal Server Error	Błąd po stronie serwera

401 Unauthorized

Najczęstsze przyczyny:

Brak nagłówka X-API-Key
Token z literówką lub obcięty
Token został usunięty

# Sprawdź, czy token jest ustawiony
echo $OGARNIAI_API_TOKEN

403 Forbidden

Token jest prawidłowy, ale nie ma wystarczającego uprawnienia. Upewnij się, że token posiada odpowiedni scope (read, write lub admin).

429 Too Many Requests

Przekroczono limit zapytań. Sprawdź nagłówek Retry-After i poczekaj wskazaną liczbę sekund.

Limity zapytań (rate limits)

Limity są naliczane na token, w oknie godzinowym.

Uprawnienie	Limit na godzinę
`read`	1 000 zapytań
`write`	2 000 zapytań
`admin`	5 000 zapytań

Nagłówki rate limit

Każda odpowiedź zawiera nagłówki informujące o stanie limitu:

Nagłówek	Opis
`X-RateLimit-Limit`	Maksymalna liczba zapytań w oknie
`X-RateLimit-Remaining`	Pozostała liczba zapytań
`X-RateLimit-Reset`	Timestamp resetu limitu (Unix epoch)
`X-RateLimit-Reset-After`	Sekund do resetu limitu
`Retry-After`	Sekund do odczekania (tylko przy 429)

Przykład nagłówków

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1705334400
X-RateLimit-Reset-After: 2145

Obsługa limitów w kodzie

Sprawdzaj nagłówki rate limit i reaguj na status 429:

import time
import requests

def safe_request(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        # Loguj stan limitu
        remaining = response.headers.get("X-RateLimit-Remaining")
        if remaining:
            print(f"Pozostalo zapytan: {remaining}")

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            print(f"Limit przekroczony, czekam {retry_after}s...")
            time.sleep(retry_after)
            continue

        response.raise_for_status()
        return response.json()

    raise Exception("Przekroczono maksymalna liczbe prob")