Error Codes

All API errors follow a consistent JSON structure:

{
  "detail": "Human-readable error message"
}

HTTP status codes

Status	Meaning	Common causes
`400`	Bad Request	Missing required fields, invalid field values, no fields to update, agent is disabled
`401`	Unauthorized	Missing or invalid `Authorization` header
`403`	Forbidden	Valid API key but insufficient permissions for this tenant or operation
`404`	Not Found	Agent ID does not exist in the registry
`429`	Too Many Requests	Rate limit exceeded — see `X-RateLimit-Reset` header
`500`	Internal Server Error	Agent execution failed, database error, or unexpected platform error

Error	Status	Detail	Resolution
Agent not found	404	`Agent 'xyz' not found`	Check the agent ID against the Agent Catalog. Agent IDs use snake_case.
Agent disabled	400	`Agent 'xyz' is disabled for tenant '...'`	Enable the agent via `PUT /ai/agents/{agent_id}/config` with `"enabled": true`.
Execution failed	500	`Agent execution failed`	Transient error. Retry after a short delay. If persistent, check agent-specific trigger data requirements.

Error	Status	Detail	Resolution
No fields to update	400	`No fields to update`	Include at least one of `mode`, `auto_act_threshold`, `enabled`, or `config` in the request body.
Invalid mode	422	Validation error	Mode must be one of: `shadow`, `active`, `disabled`.
Invalid risk level	422	Validation error	Risk level must be one of: `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`.
Config update failed	500	`Failed to update agent config`	Transient database error. Retry the request.

Error	Status	Detail	Resolution
Fetch failed	500	`Failed to fetch decisions`	Transient database error. Retry with a smaller `limit` parameter.
Invalid pagination	422	Validation error	`limit` must be between 1 and 200. `offset` must be non-negative.

Status	Retryable	Strategy
`400`	No	Fix the request
`401`	No	Fix authentication
`403`	No	Check permissions
`404`	No	Check agent ID
`429`	Yes	Wait until `X-RateLimit-Reset`, then retry
`500`	Yes	Exponential backoff starting at 1 second, max 3 retries