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.

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.

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

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. Checking a two-factor code has one too, as the next table shows.

These actions start work that takes time or resources on Coritan's side, so each has a budget of its own on top of the limits above. 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. Please wait and try again.",
    "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.

Apps answers the same way without action, and its message names what ran out, such as Too many deployments of this app. Wait a few minutes.

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).