Plans, rates and limits

Overview#

Every account has a plan, and the plan sets the account's rates, sizes and counts. This page describes each setting, what the service does when a request reaches one, and the headers that tell a client where it stands. After reading it you can size an agent's traffic to a plan and handle every limit response correctly. The current values for each plan are on the portal's pricing page, described in Pricing and billing; the Free plan's values are listed at the end of this page.

What a plan sets#

Every request counts against the request rate and the sustained request pace. A write is an Issue whose declarations half the service would act on, a removal included; it counts against the write rate and the sustained write pace as well. A queries-only Issue is a request and not a write. Rates apply to the whole account, across all its namespaces and keys.

Bursts and the sustained pace#

When a request arrives over one of its rates, the service does not refuse it at once. It computes when the request may proceed and holds it on its open connection until then; the answer then arrives normally, and its Server-Timing header includes governor;dur= with the time waited. A request is refused with 429 only when its wait would exceed the plan's maximum delay, or when the account's waiting room is full. The 429 carries a Retry-After header with the exact number of seconds until the request would be admitted. Nothing in a refused request was processed.

The sustained pace has no reset date. Its 30-day window refills continuously, by one thirtieth of the window each day, so an account that has used it up can continue at the daily pace. When the window is spent, Retry-After is the time until one more request or write fits: on the Free plan, about ten seconds for a request and about a minute for a write. The portal and the pricing page state each limit as a burst beside a sustained daily pace, for example "120 requests a minute in bursts; about 8,300 a day sustained".

The 429 body names the window:

Data out and processing time are charged after a request is answered, so a large answer is never cut short; the account's next request waits for the excess instead. Write rates are checked after the body is read, so a write over its rate waits holding its body.

Rate limits apply only to a caller the service has already admitted. A request with no key, an unknown key, or a key admitted to nothing in the namespace receives the empty 404 and never a 429, a wait or a rate-limit header.

Rate-limit headers#

Every answer to an admitted request, 2xx and 429 alike, carries the headers defined in draft-ietf-httpapi-ratelimit-headers-11. RateLimit-Policy lists the request and write windows by name: ceiling, requests, requests-30d, writes and writes-30d, each with q, the burst size, and w, the seconds a full burst takes to refill. RateLimit names one window, the one that refused the request or otherwise the one with the least room left, with r, the units remaining, and t, the seconds until it is full. A refusal on the Free plan's sustained request pace looks like this:

HTTP/1.1 429 Too Many Requests
Content-Type: text/plain; charset=utf-8
Retry-After: 11
RateLimit-Policy: "ceiling";q=20;w=1,"requests";q=600;w=300,"requests-30d";q=10000;w=103680,"writes";q=100;w=300,"writes-30d";q=2000;w=129600
RateLimit: "requests-30d";r=0;t=103680

error: this tenant's 30-day request allowance is spent for now and refills continuously; nothing was processed

Requests in flight#

Separately from the plan's rates, the service limits how many requests it works on at once for one namespace, for one account and in total. A request over the namespace or account limit is refused with 429, and one over the service-wide limit with 503; both carry a short Retry-After and a body that ends nothing was processed. These limits clear quickly, so retry after the stated interval.

Size limits#

A request body over the plan's request-size limit is refused with 413 and the body error: the request body exceeds this tenant's limit of N bytes; nothing was processed, whether the body declared its length or was sent in chunks. A 413 carries no Retry-After; split the write, or use bulk load for a large file. A body within the size limit can still be refused with 413 and a TERSE-LIM- code when a single line, name or text value is over the service's content limits.

Namespace size is the only limit that does not refill. When a namespace has reached the plan's namespace-size limit, a write that could grow it is refused with 507 and the body error: namespace 'X' is at its plan's limit of N bytes; nothing was processed, with no Retry-After. A request of up to 1 MiB whose declarations only remove is still accepted, so you can make room. A write that starts below the limit and crosses it is accepted, so a namespace can exceed the limit by at most one request.

Counts#

The plan's limits on namespaces, keys and users are checked when one is created. A namespace being copied counts from the moment the copy is requested; a disabled or deleted namespace does not count, and enabling a disabled one is checked like creating one. When an account moves to a plan with lower counts, what it already holds is kept, and new ones can be created only once the account is back under the limit.

Account status#

An account whose payment is past due keeps working during a grace period, at the Free plan's per-second and per-minute rates where those are lower than its own. Its sustained daily paces, sizes and counts are not reduced. If the grace period ends unpaid, the account is suspended: every request to its namespaces, reads included, is refused with 403 and the body error: this account is suspended; sign in to the portal for details; nothing was processed. The portal stays available so that you can resolve it. A cancelled subscription returns the account to the Free plan with its data kept. The Pricing and billing page describes the billing side.

The Free plan#

These are the Free plan's values in the plan catalog.