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#
Errors follow the standard WordPress REST format — a machine-readable code, a human-readable message, and a data object with the HTTP status:
{
"code": "invalid_parameter",
"message": "The 'date_range_preset' parameter must be one of: 1h, 4h, 12h, 24h, 7d, 30d, 90d",
"data": {
"status": 400
}
}Ability-specific errors use descriptive codes such as missing_post_id, invalid_post, or insufficient_variants, alongside WordPress REST codes such as rest_forbidden when a capability check fails.
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. |
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.