Rate Limits & Errors

Rate Limits

API requests are rate-limited per API key based on your plan:

Plan	Requests per Minute
Pro	100
Business	500

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait:

http

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

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

💡 Tip: Implement exponential backoff in your integration. Respect the Retry-After header to avoid repeated 429 responses.

Error Codes

All error responses follow the same format:

json

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

HTTP Status	Code	Description
400	VALIDATION_ERROR	Invalid request body, missing required fields, or bad parameter format
401	UNAUTHORIZED	Missing or invalid API key
403	INSUFFICIENT_SCOPE	API key lacks the required scope for this endpoint
403	FORBIDDEN	Missing permission (e.g. in a workspace)
403	PLAN_REQUIRED	Your plan does not include API access (upgrade to Pro or Business)
403	PLAN_LIMIT_REACHED	Resource limit reached on your current plan
403	KEY_LIMIT_REACHED	Maximum number of API keys for your plan
404	NOT_FOUND	Resource does not exist or you do not have access to it
409	CONFLICT	Conflict (e.g. document changed in the meantime on a save with expected_version, or an export already in progress)
413	-	Request body exceeds the maximum size (2 MB)
429	RATE_LIMITED	Too many requests - see Rate Limits above
500	INTERNAL_ERROR	Unexpected server error - contact support if persistent

Pagination

All list endpoints support offset-based pagination with limit and offset parameters:

Parameter	Type	Default	Description
limit	integer	50	Number of results per page (max 100)
offset	integer	0	Number of results to skip

Response Format

json

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

Field	Description
data	Array of results for the current page
total	Total number of matching results across all pages
limit	The limit value used for this request
offset	The offset value used for this request

Iterating Through Pages

To fetch all results, increment offset by limit until offset >= total:

bash

OFFSET=0
LIMIT=50

while true; do
  RESPONSE=$(curl -s "https://my.clarife.app/api/v1/documents?limit=$LIMIT&offset=$OFFSET" \
    -H "Authorization: Bearer clrf_your_key")

  TOTAL=$(echo $RESPONSE | jq '.total')
  COUNT=$(echo $RESPONSE | jq '.data | length')

  echo "Fetched $COUNT items (offset $OFFSET of $TOTAL)"

  OFFSET=$((OFFSET + LIMIT))
  if [ $OFFSET -ge $TOTAL ]; then
    break
  fi
done

Best Practices

Cache responses when possible

If your integration reads the same documents repeatedly, cache the results locally and use webhooks to invalidate the cache when data changes.

Use specific scopes

Grant each API key only the scopes it needs. A read-only dashboard integration should not have documents:write.

Handle errors gracefully

Always check the HTTP status code and code field. Display meaningful messages to users instead of raw error strings.

Respect rate limits

Use the Retry-After header and implement backoff. Batch operations where possible to reduce request count.