Limits
Every endpoint in this reference allows 10 requests per second per API key unless the table says otherwise, and the limits are the same on every plan.
Requests with different resource ids share a limit when their method and route pattern match. Ten requests for ten different Content Editors count as ten against
GET /api/v2/workspaces/{workspace_id}/content_editors/{id}. A burst against one endpoint does not slow the others.
Windows are fixed, not sliding: the counter resets at the end of each second or minute. Each v2 reference page prints its limit at the end of the operation description; a v1 page that prints none uses the default.
Headers
Every v2 response to an authenticated request reports the window it was counted in, including the429 itself.
Authentication runs before the counter, so a
401 carries none of them. v1 responses carry none either.
In a loop, read x-ratelimit-remaining after each response and pause until x-ratelimit-reset when it reaches 0. Other processes on the same key draw on the same allowance, so still handle 429.
Over the limit
A request over the limit is rejected before it does any work, with a429 that says how long to wait.
In v2 the wait arrives twice, in the Retry-After header and inside the error envelope, both in whole seconds. The body repeats it in details:
1, so the default one-second window always answers 1 and the per-minute windows answer up to 60. The three window headers come with the response, with x-ratelimit-remaining at 0.
v1 answers with the plain-text body Rate limit exceeded. Try again in N ms, where N is the wait in milliseconds, and sends no headers. Migrating from v1 lists the other differences.
Handle 429
Wait for Retry-After before retrying the rejected request.
- Resend the same request after the wait; in v1 the wait is the milliseconds the body names. The rejected request did not run, so resending it is safe; a request that timed out is a different case, covered under Idempotent creates.
- Spread bulk work instead of bursting. At the default limit, one request every 100 milliseconds per endpoint stays under it.
- Pace by the headers rather than by a fixed sleep when several processes share one key, because they share its allowance too.
Credits
Each operation spends at most one credit, or one use of its allowance, per request, at the moment its Cost cell names.
Each reference page repeats this as a Cost or Usage line under the operation description.
Deleting a Content Editor does not refund its credit, and the deleted editor still counts toward fair usage (Delete Content Editor).
In v1, creating a Content Editor spends one Content Editor credit; on Enterprise and some older plans, a create with
write_with_ai spends an AI article credit instead. Auto-Optimize, Audit, SERP Analyzer, and Humanizer draw on their own allowances.
When an allowance is used up
The request fails with422 and reason quota_exceeded; check Settings → Usage and your plan allowance before retrying. The message names the allowance, for example Content Editor quota exceeded or Auto-Optimize allowance exceeded.
Creating a content template or a custom voice answers the same way when you reach the number your plan allows. Those are caps on how many you can hold, not credits spent per request, so delete unused ones before creating more.
No endpoint reports remaining credits, so check the app before a bulk run that
creates Content Editors or generates articles.
- Documents per plan: the pricing page.
- Auto-Optimize allowance: your plan’s limits; plans on fair usage follow the Fair Usage Policy.
- Allowances for SERP Analyzer, Audit, and Humanizer, and the caps on templates and voices: the Fair Usage Policy.