Developers
API errors, rate limits, and retry behavior
Diagnose 401, 403, 409, 422, 429, render failures, MCP tool errors, and GraphQL errors without creating duplicate posts or exceeding shared quotas.
Updated
One account budget across three interfaces
REST /v1, MCP, and GraphQL share a budget of 120 requests per minute per account. Creating another key or switching interfaces does not create another allowance. Requests that require generate also consume an hourly generation budget of 40 scope checks per account. A compound operation can pass more than one generate check, so do not treat this as a guaranteed number of completed jobs.
| Limit | Response or behavior |
|---|---|
| Shared account request budget | HTTP 429; Retry-After: 60 |
| Generate-scope budget | REST: HTTP 429 with Retry-After: 3600; MCP: inspect the tool error |
| Plan or feature entitlement | Usually 403 with a corrective detail; not fixed by waiting one minute |
| Storage, post, or credit allowance | Operation-specific refusal; check get_usage and the returned detail |
| Active API keys | Maximum 10; revoke an unused key before creating another |
| Webhook endpoints | Maximum 5 |
| Concurrent video exports | One per account |
Match the response to the next action
| Status | Likely cause | Next step |
|---|---|---|
| 400 | Invalid source, unsupported media, unsafe URL, unknown brand, or other input rule | Read detail; correct the input before retrying |
| 401 | Missing, invalid, revoked, or expired credential; inactive owner | Check the stored key or complete OAuth sign-in again |
| 403 | Missing scope or current plan/feature entitlement | Compare scopes and feature availability; do not rotate blindly |
| 404 | Owned resource was not found | Check the returned ID and account; foreign records are not discoverable |
| 409 | Schedule collision or stale layout/memory version | Choose another slot, or read current state before editing |
| 422 | Request schema validation | Inspect field-level detail and correct types, bounds, or missing values |
| 429 | Account or generation throttle | Wait at least Retry-After, then back off with jitter |
| 502 | Design rendering failed | Keep the existing draft ID and retry rendering after checking state |
Read the error format for your interface
REST errors normally contain detail, which can be a string or structured validation list. MCP tools can fail inside HTTP 200 with result.isError: true and an explanatory content block; envelope errors use error. GraphQL execution failures can also use HTTP 200, with an errors array. Check the appropriate envelope before reporting success.
Retry only when the operation is understood
- For a throttled read, honor Retry-After and add a small random delay so workers do not restart together.
- For a write with a clear validation or permission error, change the request or access first.
- For an unknown write outcome after a network failure, reconcile the existing post, asset, or job before repeating it.
- For stale memory or layout, fetch the current version and reapply only the intended changes.
- For a long-running job, retain job_id and poll; a client deadline does not cancel the server job.
Set separate timeouts for quick reads and synchronous generation. Centralize concurrency in your integration so independent workers share the account budget. Record the method, path or tool name, safe input summary, HTTP status, response detail, and relevant resource IDs; exclude tokens, signing secrets, and private source text.
Keep document and publishing limits separate
A Canvas document can have 20 pages and 160 layers per page, while a platform may accept fewer attachments. For example, a 20-page design cannot become one 20-item Instagram carousel, whose limit is 10. Upload size, video export duration, and platform publishing restrictions are also separate checks. Passing one does not imply the next will succeed.
Frequently asked questions
Can I get a separate rate limit for each API key?
No. The request and generation budgets are per account and shared across keys, REST, MCP, and GraphQL.
What should I do with a 409 stale-layout error?
Read the latest layout and version, then reapply the intended edit. Changing only the version number on an old layout can overwrite someone else's work.