Limits and retention

This page covers everything that bounds your traffic and your data on Gate: per-key and org-level rate limits, rolling usage caps on cost, tokens, and requests, the maximum request size, and how long Gate retains your logs, metrics, and audit records.

How rate limiting works

Every request to the gateway passes through two checks, in this order:

1. Org-level rate limit. A requests-per-minute cap shared across every API key in your organization. Configured by your org admin in the dashboard or via the API.
2. Per-key rate limit. An optional cap on a single API key. Useful for sandboxing CI pipelines, shared team keys, or untrusted clients.

Both layers use a sliding window of 60 seconds. Counters are maintained per key or per org, and they do not stack. If both are configured, the org-level limit is checked first. A rejection at either layer returns HTTP 429.

Note: In multi-replica deployments, rate limit counters are shared across all gateway replicas via a distributed store. Single-replica setups use an in-process store that is accurate but does not survive pod restarts.

Rate limit response headers

All gateway responses include rate limit headers so your client can track headroom without waiting for a rejection. The exact headers present depend on which limit applied.

Per-key headers

Per-key limits set X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. No X-RateLimit-Scope header is emitted for per-key limits.

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1749254400

Org-level headers

When an org-level limit is configured, two extra headers are always set (even when the per-key limit is also active):

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 823
X-RateLimit-Reset: 1749254400
X-RateLimit-Scope: org
X-RateLimit-Org-Limit: 1000
X-RateLimit-Org-Remaining: 823

HTTP 429 response body

When any rate limit is exceeded the gateway returns HTTP 429 with an error body of the form:

{
 "error": {
 "code": "rate_limit_exceeded",
 "message": "Rate limit exceeded. Please retry after the reset window.",
 "source": "gateway",
 "retryAfter": 1749254400
 }
}

For org-level rejections the message is:

{
 "error": {
 "code": "rate_limit_exceeded",
 "message": "Organization rate limit exceeded. Please retry after the reset window.",
 "source": "gateway",
 "retryAfter": 1749254400
 }
}

The x-gate-error-source: gateway response header carries the same source value for clients that inspect headers.

Tip. Use retryAfter directly instead of sleeping for a fixed interval. The value is the exact window reset time, so you avoid both over-sleeping and premature retries.

Configuring rate limits

Per-key rate limit

Set rateLimit when creating or updating an API key via the keys API:

POST /api/v1/gateway/api-keys
Authorization: Bearer $GATE_API_KEY
Content-Type: application/json

{
 "name": "CI pipeline key",
 "orgId": "org_…",
 "rateLimit": 60
}

rateLimit is requests per minute. Set it to null (or omit it) to remove the cap. The field is also editable via PATCH /api/v1/gateway/api-keys/:id.

Org-level rate limit

Org-level limits are set by an admin in the dashboard under Settings, Rate limits. The gatewayRateLimit field on the org’s entitlements row is the source of truth. null means no org cap is applied.

Usage limits (rolling spend/token/request caps)

In addition to per-minute rate limits, paid-plan organizations can create usage limits, soft ceilings on cost, token consumption, or request count over a rolling time window (1 hour, 1 day, 1 week, or 1 month). These are separate from the sliding-window rate limiter and are checked after rate limiting, before the upstream call.

Usage limits are managed via the keys API at /api/v1/gateway/usage-limits.

Note: Usage limits require a paid plan. Attempting to create or update a limit on a free-plan org returns 403.

Create a usage limit

POST /api/v1/gateway/usage-limits
Authorization: Bearer $GATE_API_KEY
Content-Type: application/json

{
 "orgId": "org_…",
 "name": "Daily token ceiling",
 "limitType": "tokens",
 "threshold": "5000000",
 "timeWindow": "1 day"
}

Update or delete

PATCH /api/v1/gateway/usage-limits/:id
DELETE /api/v1/gateway/usage-limits/:id

PATCH accepts the same optional fields as POST (all fields are optional on update). DELETE removes the limit permanently. It does not affect historical usage data.

Inspect current usage

GET /api/v1/gateway/usage-limits/:id/usage

Returns the current rolling usage and whether the threshold has been reached:

{
 "data": {
 "limitId": "lim_…",
 "limitType": "tokens",
 "threshold": "5000000",
 "currentUsage": "3812044",
 "timeWindow": "1 day",
 "exceeded": false
 }
}

Request size

The 25 MB gateway limit matches Anthropic’s published request ceiling. Long agentic conversations that accumulate large tool-result blobs can approach it. Exceed it and the gateway returns HTTP 413 with code request_too_large.

Data retention

Every request is recorded, but the different kinds of data Gate keeps have different lifetimes, and two of them depend on your plan.

When logs are removed at the end of their window, the audit event itself (timestamp, model, cost, security outcome) is kept permanently. Only the readable content is deleted. Enterprise plans carry custom retention terms. See Plans for how retention fits into each plan.

Rate-limit and usage-limit errors

For the full error taxonomy see Error handling.

Related pages

• Authentication: how paying through Gate vs your own keys are chosen per request.
• Error handling: full error taxonomy and debugging tips.
• Plans: how limits and retention fit into Free, Pro, and Enterprise.