Skip to content

Errors

The error shape every endpoint returns and the standard error codes.

All errors follow a consistent structure:

{
"error": {
"code": "invalid_input",
"message": "Human-readable description of what went wrong",
"details": {}
}
}
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