Rate Limiting

Every authenticated API request sits behind at least one named limiter. Buckets apply per token, not per IP, because that is the unit of identity pipelines and agents share. Hit a limit and you get a 429 response wrapped in the standard error envelope with code: "RATE_LIMITED" plus a Retry-After header.

Named bucketsCopy Anchor Link

When the caller is unauthenticated, the api-token limiter falls back to a per-IP key so accidental traffic bursts are still caught.

Response headersCopy Anchor Link

Every rate-limited response carries the standard rate-limit headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 278
Retry-After: 47

Honour Retry-After before retrying; it reports the number of seconds until the bucket refills.

Error shapeCopy Anchor Link

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "The rate limit for this token has been exceeded.",
    "remediation": "Back off and retry after the time hinted by the Retry-After header.",
    "docs_url": "https://docs.example.test/api/v1/errors#rate-limited",
    "request_id": "00-abc..."
  }
}

Designing pipelines and agentsCopy Anchor Link

• Polling: keep the interval at 15 seconds or more per poller, and prefer webhooks for anything that must react quickly.
• Bulk imports: chunk writes into batches of 100 to 200 and respect Retry-After when a 429 fires. Concurrency does not beat the limiter; it counts concurrent calls the same as sequential ones.
• Agents: assume the bucket is shared across every call the agent makes with one token. Hitting the limit in practice usually means a tight loop on the agent's side.

Upstream capsCopy Anchor Link

The hourly cap (10,000 requests) deliberately allows a sustained rate of about 160 requests a minute before the per-minute ceiling kicks in. If an integration needs a higher sustained rate, raise it with your administrator, who can adjust the limit for your workspace.