Error Handling

AI integrations should treat errors as part of the workflow, not as free-form text to ignore. The API returns structured errors with codes, messages, and hints for resolution.

Error response format#

text

{
  "code": "invalid_parameter",
  "message": "The 'date_range_preset' parameter must be one of: 1h, 4h, 12h, 24h, 7d, 30d, 90d",
  "data": {
    "status": 400,
    "param": "date_range_preset",
    "provided": "1w",
    "allowed": ["1h", "4h", "12h", "24h", "7d", "30d", "90d"]
  }
}

Common error classes#

Error	Meaning	Recommended handling
Validation	Required input is missing or invalid.	Ask for the missing input or retry with corrected arguments.
Permission	The current user or integration cannot call the ability.	Stop and request access rather than trying another mutation.
Not found	The target content, experiment, audience, or export does not exist.	Search for the object or ask the operator to choose from candidates.
Conflict	The object state changed or the requested operation is not valid now.	Refresh state before proposing the next action.
Upstream	Analytics or export services failed or timed out.	Retry only when the operation is safe and idempotent.

Common error codes#

Code	Status	Description
`rest_forbidden`	403	User lacks the required capability.
`invalid_parameter`	400	Parameter value is invalid or out of range.
`missing_parameter`	400	Required parameter was not provided.
`not_found`	404	Requested resource does not exist.
`rate_limit_exceeded`	429	Too many requests.

Destructive actions#

Some abilities are marked as destructive because they modify or finalize live data in ways that are hard to reverse. Agents should require explicit confirmation before calling accelerate/remove-variant, accelerate/stop-experiment, or accelerate/broadcast-content.

Agent behavior#

Agents should surface the precise blocker and the next safe action. They should not invent results when an ability fails.