Skip to main content

​
Rate Limits

API requests are rate-limited per API key based on your plan:
PlanRequests per Minute
Pro100
Business500
When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait: 
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "Rate limit exceeded. Try again in 12 seconds.",
  "code": "RATE_LIMITED"
}
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: 
{
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}
HTTP StatusCodeDescription
400VALIDATION_ERRORInvalid request body, missing required fields, or bad parameter format
401UNAUTHORIZEDMissing, invalid, or expired API key
403FORBIDDENAPI key lacks the required scope for this endpoint
403PLAN_REQUIREDYour plan does not include API access (upgrade to Pro or Business)
403KEY_LIMIT_REACHEDMaximum number of API keys for your plan
404NOT_FOUNDResource does not exist or you do not have access to it
413PAYLOAD_TOO_LARGERequest body exceeds the maximum size (10 MB)
429RATE_LIMITEDToo many requests — see Rate Limits above
500INTERNAL_ERRORUnexpected server error — contact support if persistent

​
Pagination

All list endpoints support cursor-based pagination with limit and offset parameters:
ParameterTypeDefaultDescription
limitinteger50Number of results per page (max 100)
offsetinteger0Number of results to skip

​
Response Format

{
  "data": [...],
  "total": 142,
  "limit": 50,
  "offset": 0
}
FieldDescription
dataArray of results for the current page
totalTotal number of matching results across all pages
limitThe limit value used for this request
offsetThe offset value used for this request

​
Iterating Through Pages

To fetch all results, increment offset by limit until offset >= total: 
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

If your integration reads the same documents repeatedly, cache the results locally and use webhooks to invalidate the cache when data changes.
Grant each API key only the scopes it needs. A read-only dashboard integration should not have documents:write.
Always check the HTTP status code and code field. Display meaningful messages to users instead of raw error strings.
Use the Retry-After header and implement backoff. Batch operations where possible to reduce request count.