When a call fails, the service returns the following error structure, where request_id matches the x-request-id response header:
{
"type": "error",
"error": {
"code": "AGENT_001",
"message": "Agent not found"
},
"request_id": "35feaacc-7914-948f-a38e-010bf8095bc1"
}
Common error codes
| code | HTTP status | Description |
|---|
| AGENT_001 | 404 | Agent not found |
| 400 | 400 | Parameter validation failed; message gives the reason (for example, limit must be between 1 and 100) |
| InvalidApiKey | 401 | API Key missing or invalid (gateway layer) |
| Endpoint.AccessDenied | 403 | Workspace does not exist or is not accessible (gateway layer) |
| BadRequest.IllegalEndpoint | 400 | Workspace route is invalid (gateway layer) |
Authentication and workspace-routing errors are returned directly by the gateway in a flat {"request_id", "code", "message"} structure; business errors are returned by the service, with the error code in error.code.
Common HTTP status codes
| HTTP status | Description |
|---|
| 400 | Missing parameter, malformed format, or value out of range |
| 401 | Invalid API Key |
| 403 | No access to the workspace |
| 404 | Resource not found |
| 409 | The current resource state does not allow this operation |
| 429 | Too many requests |
| 500 | Internal service error |
When troubleshooting, use request_id to locate the specific request. Continue with the endpoint list in the Overview. 
