Guides
Errors & Rate Limits
The error envelope, the full error catalog, and rate-limit behavior.
Error envelope
All errors share one envelope and use correct HTTP status codes:
{ "error": { "message": "Insufficient scope. This action requires: posts:write.", "code": "INSUFFICIENT_SCOPE" } }details may be present (e.g. an array of validation messages) on validation
errors.
Error catalog
| Code | HTTP | Meaning |
|---|---|---|
UNAUTHORIZED | 401 | Missing or invalid API key. |
ENDPOINT_NOT_AVAILABLE | 403 | This endpoint is not reachable with an API key. |
INSUFFICIENT_SCOPE | 403 | The key lacks the scope this action requires. |
NO_ACTIVE_SUBSCRIPTION | 403 | The workspace has no active paid subscription. |
TIER_UPGRADE_REQUIRED | 403 | The action requires a higher plan (e.g. recurring posts, approvals). |
WORKSPACE_FORBIDDEN | 403 | The key's creator no longer belongs to the key's workspace. |
NOT_FOUND | 404 | The requested resource does not exist or is not accessible. |
INVALID_PARAMETERS | 422 | Request parameters failed validation. |
API_KEY_LIMIT_REACHED | 422 | The workspace already has an active API key. |
PLAN_LIMIT_REACHED | 422 | The user already has the maximum of 10 content plans. |
INVALID_STATE | 422 | The resource isn't in a state this action can be applied to. |
GENERATION_FAILED | 422 | AI generation could not produce content. |
quota_exceeded | 422 | The monthly Quote Week (image generation) run quota is exhausted. |
RATE_LIMIT_EXCEEDED | 429 | Per-IP or per-endpoint rate limit exceeded. |
DAILY_LIMIT_EXCEEDED | 429 | The plan's daily AI-generation quota is exhausted. |
Rate limits
Every /api/v1/* response carries IETF-style rate-limit headers:
RateLimit-Limit: requests allowed in the current windowRateLimit-Remaining: requests left in the windowRateLimit-Reset: seconds until the window resets
A global ceiling of 100 requests/minute per IP applies to all endpoints. Specific endpoints have tighter per-token limits:
| Endpoint(s) | Limit |
|---|---|
POST /posts/generate | 10 / minute |
POST /posts/generate_batch, /generate_thread, /generate_carousel | 6 / minute (shared bucket) |
POST /posts/{post_id}/publishes | 30 / minute |
POST /linkedin/video_uploads | 10 / hour |
On 429 the response body is
{ "error": { "message": "...", "code": "RATE_LIMIT_EXCEEDED", "retry_after": 42 } }and a Retry-After header (seconds) is included. AI-generation endpoints
additionally return 429 DAILY_LIMIT_EXCEEDED when your plan's daily
generation quota is exhausted.