Rate limits

The Coritan API limits how many requests it takes from one address, how many failed sign-ins it accepts, and how often you can repeat an action that costs a lot to carry out. A request over any limit answers 429 Too Many Requests, and the Retry-After header says how many seconds to wait.

Every limit on this page that counts an IP address counts an IPv4 address on its own, and an IPv6 address by its /64 network: the block a provider gives one subscriber. All the addresses in one IPv6 /64 share a single budget, so moving to another address in that block does not reset a limit. An IPv4 address written in IPv6 form, such as ::ffff:203.0.113.10, counts as the IPv4 address.

The proxy's limits are its defaults, and Coritan can change them. When the proxy refuses 8 requests in a row from one address, it blocks that address for 5 minutes. While the block lasts, every request answers 429 and every new connection is closed, so do not retry at once after a 429.

The API also limits requests by the work it takes to answer them. Each API server applies these limits on its own:

While the database is under strain, a request with no Authorization header to a route that reads the database can also answer that 503. Requests from signed-in accounts are answered first. Wait as long as Retry-After says, then repeat the request; sending more at once only extends the wait.

Only failures count towards these limits: an answer of 401 or 403. A sign-in that works costs nothing.

An organization's sign-in, POST /orgs/{org_slug}/auth/login, has one more 429. When the organization has linked an old site and that site asks the person to wait, the answer is {"detail": "Too many sign-in attempts. Wait a few minutes and try again.", "code": "rate_limited"} with Retry-After: 300, and it counts as a failed attempt from that IP address.

POST /auth/forgot-password always answers 200, so it has a budget that counts every request instead: 10 in 15 minutes from one IP address, and 3 in 15 minutes for one email address. An organization's POST /orgs/{org_slug}/auth/forgot-password has two as well, in the next table. Checking a two-factor code has one too.

These are the main actions with a budget of their own, on top of the limits above. Most start work that takes time or resources on Coritan's side, and the rest guard a request that writes a record or sends a message. The budget counts your requests for one server, instance or route, or for your whole account where the table says so.

The matching routes of an organization's customer portal, under /orgs/{org_slug}/portal/, have the same budgets for each customer. The staff console has budgets of its own on actions such as charges, refunds, credit and exports.

Over a budget, the action answers:

{
  "detail": {
    "error": "rate_limited",
    "message": "Too many requests for this action. Try again later.",
    "action": "container.power",
    "retry_after_seconds": 60
  }
}

retry_after_seconds and the Retry-After header both give the length of the whole window. Waiting that long always frees the budget.

org_customer.forgot is the one budget that does not answer 429. A forgot-password request that is over it gets the same 200 as every other, so an address that has no account looks the same as one that does. Both forgot-password budgets count addresses that have no account.

App Deployment and the Apps API answer the same way without action, and the message names what ran out, such as Too many releases of this app. Wait a few minutes. An Object Storage budget answers the same way without action.

Organization API key

Each key has its own limit, set when it is created: 4,000 requests in any 60 minutes by default. Over it, the Commerce API answers 429 with API key rate limit exceeded and Retry-After: 3600. Create organization API keys sets the limit.

Store API payments

Starting a payment and completing a cart each allow 20 tries for one cart in 10 minutes, and 60 from one IP address for one store. Over either, the Store API answers 429 with "error": "rate_limited", the message Too many payment attempts for this cart. Try again in a few minutes. and Retry-After: 600.

SMTP Relay has sending limits of its own, which SMTP Relay sending limits describes.

• Read Retry-After, a whole number of seconds, and send nothing more to that route until it has passed.
• When an answer has no Retry-After, wait 1 second, then double the wait after each 429 up to a minute, with a random part added so that many clients do not retry at the same moment.
• Never retry in a loop without a wait: 8 refusals in a row block your address for 5 minutes.
• Poll less often, and read a list once instead of one record at a time (Pagination and filtering).
• When you retry a payment or an order after a 429 or a lost connection, send the same Idempotency-Key, so that it happens only once (Idempotent requests).