Rate Limiting

Every authenticated request to /api/v1 is counted against a per-token budget of 60 requests per minute. The bucket is keyed on the token, not the user - two tokens belonging to the same person each get an independent 60/min budget.

Response headers

Every response carries the current bucket state:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45

X-RateLimit-Limit - the bucket size (always 60).
X-RateLimit-Remaining - requests left until the window resets.

A 429 response adds two headers:

Retry-After - seconds to wait before the next request.
X-RateLimit-Reset - UNIX timestamp at which the bucket refills.

When you hit the limit

If you exceed the budget, the next request returns 429 Too Many Requests with a Retry-After header in seconds:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 30
X-RateLimit-Reset: 1735689600
Content-Type: application/json

{
  "message": "API rate limit exceeded. Please try again later."
}

Best practices

Honour Retry-After. Don't retry sooner - you'll just stay throttled.
Use exponential back-off for repeated 429s (e.g. 1s, 2s, 4s, 8s, max 60s). The official SDK does this automatically.
Spread your traffic - bursting 60 requests in the first second and idling for 59 is allowed but fragile. Spacing requests reduces collisions with other tokens you may run.
Use Operations for bulk work. A single POST /v1/operations of type asset_bulk_update costs 1 request regardless of how many assets you touch.
Listen with Webhooks instead of polling. Polling for changes will eat your budget; events are pushed to your endpoint as they happen.

SDK behaviour

The official TypeScript SDK (@freedam/sdk) retries a request that gets a 429 or 5xx response, or a network error, up to 3 times by default. It waits for the Retry-After value when the response has one, and otherwise uses exponential back-off (1s, 2s, 4s, capped at 30s). Configure with maxRetries:

const client = new FreedamClient({
    baseUrl: 'https://your-freedam-instance.com',
    token: process.env.FREEDAM_TOKEN!,
    maxRetries: 5, // default is 3
});

Asking for a higher limit

The limit is 60 requests per minute for every token and cannot be set per token. Each token has its own budget, so separate integrations should use separate tokens. For bulk migrations, backfills and high-volume publishing pipelines, use Operations and Webhooks. If that is not enough, contact support.