Errors & rate limits

All error responses use the same JSON envelope:

{
  "success": false,
  "error": "Human-readable explanation",
  "code": "MACHINE_READABLE_CODE"
}

Error codes

HTTP	Code	When	Action
404	`NOT_FOUND`	Token unknown or revoked by the founder	Ask the founder for a new share link
410	`EXPIRED`	Token past `share_expires_at`	Ask the founder to create a new link (7-day default)
422	`VALIDATION_ERROR`	Missing token in URL	Check request path
429	`RATE_LIMITED`	> 60 requests/minute per IP per token	Back off; retry after 60 seconds
503	`STATUS_UNAVAILABLE`	API temporarily disabled	Retry later; contact support if persistent
503	`RATE_LIMIT_UNAVAILABLE`	Rate limiter unavailable (production)	Retry shortly
500	`STATUS_ERROR`	Internal assembly failure	Retry; contact support if persistent

Rate limits

Limit	Value
Requests per minute	60
Scope	Per client IP and per token
Window	Rolling 60-second window

When rate limited, you receive 429 with code RATE_LIMITED.

Best practice: cache responses for at least 15 minutes in screening pipelines. Compliance scores change when founders update their Klarify profile — not on every API call.

CORS

The API is intended for server-to-server integration. Browser-side calls from your web app may be blocked by CORS unless your origin is allowlisted. Call the API from your backend.

Idempotency

GET requests are safe and idempotent. Each successful call increments meta.view_count (audit trail for founders).

Support

Issues with tokens, missing data, or integration questions:

Email: [email protected]

Include the HTTP status code and code field — do not send full tokens in support emails; send the first 8 characters only.