Developers

Errors and rate limits

What each status code means, the default rate limits and how to retry safely.

On this page

Status codes
Rate limits
Retrying safely

Errors come back as JSON with an error field, and usually a message. Use the HTTP status first, then the body.

Status codes#

Status	Meaning	What to do
`200`, `201`	The call worked.	Read the body.
`401`	No valid sign-in. The message says why, for example `No token provided`, `Token has been revoked` or `Session ended`.	Sign in again.
`403`	You are signed in but your role is not allowed. The body names the `component` and the level `required`.	Ask an administrator, or hide the action.
`409`	A newer edit exists. Documents answer with `DOCUMENT_CONFLICT`.	Reload and try again.
`429`	Too many requests.	Wait, then retry.
`503`	The server cannot verify your session right now.	Retry shortly. Keep your session.
`500`	Something failed on the server.	Retry later. If it keeps happening, contact support.

An example 401:

json

{ "error": "Access denied", "message": "No token provided" }

Rate limits#

These are the defaults. A deployment can change them.

Limit	Applies to
2,000 requests per 15 minutes	All API calls, counted per signed-in user (or per address when not signed in).
20 failed sign-ins per 15 minutes	Sign-in attempts for the same address and email. Successful sign-ins are not counted.
120 requests per minute	The AI content routes under `/api/ai`, per user.

Responses include the standard RateLimit headers, so a client can see how much is left. A refused call looks like this:

json

{ "error": "Rate limit exceeded", "message": "Too many requests, please slow down." }

Retrying safely#

Retry 429 and 503 with a growing wait. Do not retry 401 or 403 without changing something first.

async function call(url, options, tries = 4) {
  for (let i = 0; i < tries; i++) {
    const res = await fetch(url, options);
    if (res.status !== 429 && res.status !== 503) return res;
    await new Promise((r) => setTimeout(r, 500 * 2 ** i)); // 0.5s, 1s, 2s, 4s
  }
  throw new Error("Still rate limited. Try again later.");
}

Need more help?

Can’t find what you need? Talk to the team.

Contact support

PreviousDocuments API