Error Codes

Use normalized error codes so operators and integrations can react deterministically.

Authentication and authorization

• unauthorized
• permission_denied
• organization_mismatch

Validation and request issues

• invalid_payload
• missing_field
• unsupported_operation

Agent and execution issues

• agent_not_found
• agent_not_ready
• execution_timeout
• step_failed

Infrastructure and dependency issues

• external_service_error
• storage_unavailable
• queue_unavailable

Billing and usage issues

• subscription_required
• usage_limit_reached
• billing_provider_error

Response guidance

Return both code and context:

{
  "error": "usage_limit_reached",
  "message": "Task run limit reached for current billing period",
  "details": {
    "plan": "starter",
    "remaining": 0
  }
}

Keep public messages safe and avoid leaking secrets or internal topology.