API Reference
Errors
Error response format, status codes, rate limits, and retry guidance
Every API error response uses this envelope:
{
"error": {
"type": "validation_error",
"code": "missing_document_url",
"message": "document_url is required and must be a string",
"request_id": "req_abc123def456"
}
}Error Types
| Type | Status | Meaning |
|---|---|---|
authentication_error | 401 | Missing, invalid, expired, or revoked key |
authorization_error | 403 | Key is valid but lacks the required scope |
validation_error | 400 | Invalid body, path, query, or idempotency use |
not_found | 404 | Resource does not exist for the organization |
billing_error | 402 | Live billing or live usage gate blocked |
precondition_error | 428 | Required legal or setup precondition missing |
rate_limit_error | 429 | Per-key rate limit exceeded |
internal_error | 500 | Unexpected Klarefi server error |
Rate Limits
Authenticated success responses include:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests per minute |
X-RateLimit-Remaining | Remaining requests in the window |
X-RateLimit-Reset | Epoch seconds when the window resets |
When the limit is exceeded, Klarefi returns 429 rate_limit_error and may
include Retry-After.
Retry Guidance
Retry 429 responses after the rate-limit reset. Retry network failures with
the same idempotency key. Do not blindly retry 400, 401, 403, 404,
402, or 428 responses; those require a request or account-state change.