Errors

All error responses share the same structure.

Error Response Structure

{
  "request_id": "req-xxxxxxxx",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Agent 'agent-001' not found in workspace 'ws-001'.",
    "details": {
      "agent_id": "agent-001",
      "workspace_id": "ws-001"
    }
  }
}

HTTP Status Codes

Status	Meaning	Client should
`200`	Success	Use the response data
`201`	Created	Use the resource ID in the response
`204`	Success, no content	Don't parse the body
`400`	Bad parameters	Fix the request, don't retry
`401`	Unauthenticated	Check the token, don't retry
`403`	Forbidden	Check ACL, don't retry
`404`	Not found	Fix the request, don't retry
`409`	Conflict (e.g. duplicate create)	Depends on the case (conflicts may be retryable)
`422`	Business validation failed	Fix the request
`429`	Rate limited	Backoff retry (see Rate limits)
`500`	Internal server error	Backoff retry
`502 / 503 / 504`	Gateway / service unavailable	Backoff retry

Business Error Codes

code	Meaning
`INVALID_REQUEST`	Bad parameter format
`RESOURCE_NOT_FOUND`	Resource doesn't exist
`FORBIDDEN`	ACL denied
`UNAUTHORIZED`	Invalid token
`RATE_LIMITED`	Rate limit exceeded
`QUOTA_EXCEEDED`	Credit / capacity exceeded
`MODEL_UNAVAILABLE`	Model temporarily unavailable (Failover already attempted)
`TOOL_INVOCATION_FAILED`	Tool call failed
`KB_INDEX_NOT_READY`	Knowledge base index not yet ready
`INTERNAL_ERROR`	Internal server error

Retry Policy

Error	Retry	Backoff
`400 / 401 / 403 / 404 / 422`	Don't	—
`409`	Depends	One immediate retry, then give up
`429`	✓	Honor `Retry-After` header
`500 / 502 / 503 / 504`	✓	Exponential backoff (1s → 2s → 4s → 8s, up to 5 attempts)

Diagnosis: request_id

Every response carries a request_id. When reporting issues, include the request_id — ops can find the full trace within milliseconds.

Error Response Structure

HTTP Status Codes

Business Error Codes

Retry Policy

Diagnosis: request_id

Next Steps

On this page