Skip to main content

​
Limity zapytań (rate limiting)

Limity są naliczane per klucz API w oknie 1 minuty.
PlanLimit zapytań
Pro100 req/min
Business500 req/min

​
Odpowiedź 429

Przy przekroczeniu limitu API zwraca status 429 Too Many Requests z nagłówkiem Retry-After: 
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED"
}
Nagłówek Retry-After podaje liczbę sekund do odczekania przed kolejnym zapytaniem.

​
Limity zasobów per plan

ZasóbFreeProBusiness
Dokumenty10200nieograniczone
Projekty330nieograniczone
Aktywne udostępnienia350nieograniczone
Storage500 MB50 GB500 GB
Klucze API—520
Subskrypcje webhooków—320

​
Paginacja

Endpointy listowe przyjmują parametry paginacji:
ParametrTypDomyślnieOpis
limitinteger50Wyniki na stronę (1-100)
offsetinteger0Przesunięcie od początku
Format odpowiedzi: 
{
  "data": [...],
  "total": 142,
  "limit": 50,
  "offset": 0
}
Aby pobrać kolejną stronę, zwiększ offset o wartość limit: 
# Strona 1
curl "https://my.clarife.app/api/v1/documents?limit=50&offset=0" ...

# Strona 2
curl "https://my.clarife.app/api/v1/documents?limit=50&offset=50" ...

# Strona 3
curl "https://my.clarife.app/api/v1/documents?limit=50&offset=100" ...

​
Maksymalny rozmiar body

Zapytania z body (POST, PATCH) mają limit 2 MB. Przekroczenie zwraca 413 Payload Too Large.

​
Kody błędów

Status HTTPKodOpis
400VALIDATION_ERRORNieprawidłowe dane wejściowe (brakujące pola, za długi tekst)
401UNAUTHORIZEDBrak lub nieprawidłowy klucz API
403INSUFFICIENT_SCOPEKlucz API nie ma wymaganego scope
403FORBIDDENBrak uprawnień (np. w workspace)
403PLAN_REQUIREDFunkcja wymaga wyższego planu
403PLAN_LIMIT_REACHEDOsiągnięto limit zasobu na bieżącym planie
404NOT_FOUNDZasób nie istnieje lub brak dostępu
409CONFLICTKonflikt (np. eksport już w toku)
413—Body zapytania przekracza 2 MB
429RATE_LIMITEDPrzekroczono limit zapytań
500—Wewnętrzny błąd serwera

​
Format odpowiedzi błędu

Wszystkie błędy mają jednolity format JSON: 
{
  "error": "Opis błędu po angielsku",
  "code": "ERROR_CODE"
}
Komunikaty błędów (error) są po angielsku i przeznaczone dla deweloperów, a nie użytkowników końcowych. Pole code służy do programowej obsługi błędów.

​
Dobre praktyki

Obsługuj 429

Implementuj exponential backoff lub respektuj nagłówek Retry-After.

Paginuj dane

Nie pobieraj wszystkiego na raz. Używaj limit i offset.

Sprawdzaj kody błędów

Używaj pola code zamiast parsowania komunikatu error.

Minimalne scopy

Nadawaj kluczom tylko wymagane scopy.