Every error uses the same JSON shape, so one handler covers them all.
{
"error": {
"code": "forbidden",
"message": "this API key is missing the \"write\" scope"
}
}
Status codes
| Status | code | When |
|---|---|---|
| 400 | validation_error | The body or query failed validation. error.fields names each field |
| 401 | unauthorized | The key is missing, invalid, revoked or disabled |
| 402 | plan_limit | Your plan doesn't include this, or a plan limit was reached |
| 403 | forbidden | The key lacks the scope this endpoint needs |
| 404 | not_found | The resource doesn't exist in this workspace |
| 429 | rate_limited | Too many requests from this key |
| 500 | internal_error | Something went wrong on our side. Retry with backoff |
Rate limits
Each key can make 120 requests every 60 seconds, shared between the REST API and the MCP server. Responses include the standard RateLimit and RateLimit-Policy headers, so you can slow down before you hit the limit.
Good practice
- Retry
429and5xxresponses with exponential backoff. Don't retry4xxerrors other than429. - Keep keys on your server. Never ship them in a browser or mobile app.
- Use a separate key per app, so you can rotate or revoke one without breaking the others.
Was this helpful?
Ship on-brand posts in minutes
Back to documentationAI content, scheduling, engagement and a full marketing suite — free to start.
Start free
