Rate Limits

The Crane Ledger REST API applies rate limits to ensure fair usage and system stability. This page describes the limits, how they are communicated in responses, and how to handle rate limit errors.

Limits by Key Type

Limits are applied per API key. Additional organization-level or global limits may apply.

Rate Limit Headers

Responses include headers that describe the current rate limit state:

Example:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1640995200

Use these headers to throttle your client or show usage in a dashboard. When X-RateLimit-Remaining is low, slow down or wait until X-RateLimit-Reset before sending more requests.

Rate Limit Exceeded (429)

When you exceed the rate limit, the API returns 429 Too Many Requests with a JSON body:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "API rate limit exceeded. Try again later.",
    "retry_after": 60,
    "status": 429
  }
}

The retry_after value is the suggested number of seconds to wait before retrying. The response may also include a Retry-After HTTP header with the same or similar value.

Retry Strategies

Exponential Backoff

When you receive a 429, wait and retry with increasing delay:

Best Practices

1. Honor retry_after – Use the value in the error body or Retry-After header before retrying.
2. Use exponential backoff – For repeated 429s, increase wait time (e.g. 1s, 2s, 4s) instead of fixed intervals.
3. Throttle proactively – Track X-RateLimit-Remaining and slow down before hitting the limit.
4. Batch when possible – Reduce request count by using bulk or list endpoints instead of many single-resource calls.
5. Use multiple keys only when appropriate – Creating many keys to bypass limits is not allowed; use a single key per environment and throttle client-side.

Credits vs Rate Limits

Crane Ledger uses both rate limits (requests per minute) and a credit system (cost per operation). You can be under the rate limit but still get a 402 Payment Required or credit-related error if your organization has insufficient credits. Monitor both:

• Rate limits – Use X-RateLimit-* headers and 429 responses.
• Credits – Use the Dashboard or billing endpoint to track balance.

• ✨ For LLMs/AI assistants: Read our structured API reference