Limity i błędy

Limity zapytań (rate limiting)

Limity są naliczane per klucz API w oknie 1 minuty.

Plan	Limit zapytań
Pro	100 req/min
Business	500 req/min

Odpowiedź 429

Przy przekroczeniu limitu API zwraca status 429 Too Many Requests z nagłówkiem Retry-After:

http

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED"
}

💡 Wskazówka: Nagłówek Retry-After podaje liczbę sekund do odczekania przed kolejnym zapytaniem.

Limity zasobów per plan

Zasób	Free	Pro	Business
Dokumenty	5	nieograniczone	nieograniczone
Projekty	1	nieograniczone	nieograniczone
Aktywne udostępnienia	3	nieograniczone	nieograniczone
Storage	100 MB	10 GB	100 GB
Klucze API	-	5	20
Subskrypcje webhooków	-	3	20

Paginacja

Endpointy listowe przyjmują parametry paginacji:

Parametr	Typ	Domyślnie	Opis
limit	integer	50	Wyniki na stronę (1-100)
offset	integer	0	Przesunięcie od początku

Format odpowiedzi:

json

{
  "data": [...],
  "total": 142,
  "limit": 50,
  "offset": 0
}

Aby pobrać kolejną stronę, zwiększ offset o wartość limit:

bash

# 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 HTTP	Kod	Opis
400	VALIDATION_ERROR	Nieprawidłowe dane wejściowe (brakujące pola, za długi tekst)
401	UNAUTHORIZED	Brak lub nieprawidłowy klucz API
403	INSUFFICIENT_SCOPE	Klucz API nie ma wymaganego scope
403	FORBIDDEN	Brak uprawnień (np. w workspace)
403	PLAN_REQUIRED	Funkcja wymaga wyższego planu
403	PLAN_LIMIT_REACHED	Osiągnięto limit zasobu na bieżącym planie
404	NOT_FOUND	Zasób nie istnieje lub brak dostępu
409	CONFLICT	Konflikt (np. dokument zmieniony w międzyczasie przy zapisie z expected_version, eksport już w toku)
413	-	Body zapytania przekracza 2 MB
429	RATE_LIMITED	Przekroczono limit zapytań
500	INTERNAL_ERROR	Wewnętrzny błąd serwera

Format odpowiedzi błędu

Wszystkie błędy mają jednolity format JSON:

json

{
  "error": "Opis błędu po angielsku",
  "code": "ERROR_CODE"
}

ℹ️ Informacja: 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.