Errors
The error shape every endpoint returns and the standard error codes.
Error format
Section titled “Error format”All errors follow a consistent structure:
{ "error": { "code": "invalid_input", "message": "Human-readable description of what went wrong", "details": {} }}Standard error codes
Section titled “Standard error codes”| HTTP | Code | Description |
|---|---|---|
| 400 | invalid_input |
Request body validation failed |
| 400 | invalid_operation |
Operation not valid for current state |
| 401 | unauthorized |
Missing, invalid, expired, or revoked API key |
| 403 | forbidden |
Key lacks required scopes |
| 404 | not_found |
Resource not found or doesn’t belong to your org |
| 409 | conflict |
Resource state conflict (e.g., job already in progress) |
| 409 | already_approved |
Brief already approved |
| 409 | not_ready |
Artifacts not yet available |
| 402 | insufficient_credits |
Not enough credits to run this job |
| 402 | copywriter_allowance_exhausted |
Core completed-outcome allowance has been used for the current period |
| 403 | plan_required |
Active subscription required |
| 403 | plan_limit_exceeded |
Plan limit reached (e.g., max tracking projects) |
| 429 | rate_limit_exceeded |
Too many requests |
| 429 | usage_limit_reached |
Pooled on-demand usage is paused until retry_at; scheduled work remains protected |
| 429 | capacity_reached |
Tracker is too busy to start a scan; retry after Retry-After |
| 429 | concurrency_limit_reached |
Your organization already has the maximum number of these jobs running; retry when one finishes |
| 410 | credit_balance_retired |
This pooled account uses /usage, not a credit balance |
| 503 | service_unavailable |
Queue service unavailable |
