Policies, limits and version lifecycle

API Studio

A policy is a named set of limits. Attach one to a version, to a client, or to both. Managing policies and attaching them to a version needs the API deploy permission. Attaching one to a client needs the API client permission.

What a policy holds

Setting	Effect
Rate limit	Calls per minute for each client.
Quota	Calls per minute, hour, day or month for each client.
IP allowlist	IPv4 and IPv6 addresses or CIDR ranges allowed to call.
CORS origins	Exact origins, as https://app.example.com, or *.
Maximum body size	Largest request body accepted, in bytes.

The Policies page

Open Policies from the API Studio overview to list, create, edit and delete policies.

• Leave a number blank for no limit. A blank Quota period uses the default.
• Enter one IP address, CIDR range or origin per line.

Attach a policy to a client on API Studio > Operate > Access. See Clients and keys.

When a version and a client both have a policy

• The lower rate limit and the lower body size apply.
• Both quotas apply.
• A caller must be in both IP allowlists.
• The client's CORS origins replace the version's.

Account limits set by your administrator cap every policy value.

Responses

Status	Meaning
403	The caller's IP or origin is not allowed.
413	The request body is larger than the limit.
429	The rate limit or quota is used up. Retry-After gives the seconds to wait.
410	The version is retired.
502	The flow's response is larger than the account limit.

When your administrator turns them on, every answer also carries RateLimit and RateLimit-Policy headers (IETF draft).

A CORS preflight (OPTIONS) from an allowed origin answers 204. A disallowed origin gets no Access-Control-Allow-Origin header.

Deprecating and retiring a version

A published version can be deprecated with an optional sunset date and a link to migration notes. Deprecating and retiring need the API deploy permission. Each answer from a deprecated version carries:

• Deprecation: @<unix time> (RFC 9745)
• Sunset: <date> (RFC 8594), when a sunset date is set
• Link: <url>; rel="deprecation", when a link is set

A deprecated version keeps answering after its sunset date until you retire it. Retiring is final: the version answers 410 and cannot be deployed again.

Idempotency keys

Send Idempotency-Key: <key> on a POST to make a retry safe (IETF draft). Keys are kept for each client for 24 hours by default.

• A repeat with the same key and body returns the first response with Idempotent-Replayed: true.
• The same key with a different body answers 409.
• A repeat while the first request is still running answers 409.
• An endpoint marked as requiring a key answers 422 when the header is missing.
• A 5xx answer is not kept, so a retry runs the flow again.

Caching GET responses

Caching is off unless an endpoint has a cache time. A cached GET answer is kept for each client and query and carries an ETag. Send it back as If-None-Match to get 304 Not Modified.

Call analytics

Each call records the endpoint, client, environment, status, duration and request and response sizes. Bodies and keys are never recorded, and the caller's IP is shortened to its network part. Analytics show calls, client errors, server errors and p50 and p95 duration, by endpoint, client or environment, per hour or day, for up to 90 days. Call records are kept for 30 days by default. See API analytics.