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 successful response carries the current bucket state:

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

X-RateLimit-Limit — the bucket size (always 60).
X-RateLimit-Remaining — requests left until the window resets.
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
Retry-After: 30
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 SDKs do 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 idempotent requests up to 3 times by default with exponential back-off and respects Retry-After. 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 60/min limit suits day-to-day automation; bulk migrations, backfills, and high-volume publishing pipelines may need more. Contact your workspace administrator — limits are enforced in code and can be raised per token by support if your use case warrants it.