API Error Codes & Troubleshooting Guide
Understand API error responses, debugging techniques, troubleshooting workflows, and implementation solutions.
{
"error": {
"code": "AGENT_NOT_FOUND",
"message": "Agent with ID 'abc-123' not found.",
"status": 404,
"correlation_id": "req-xyz-789"
}
}
HTTP Status Codes
| Code | Meaning | When |
|---|
| 200 | OK | Successful request |
| 201 | Created | Resource created successfully |
| 400 | Bad Request | Invalid parameters or request body |
| 401 | Unauthorized | Missing or invalid Bearer token |
| 403 | Forbidden | Insufficient RBAC permissions |
| 404 | Not Found | Resource does not exist |
| 409 | Conflict | Duplicate resource or version conflict |
| 422 | Unprocessable | Validation error in request body |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Server Error | Internal error — contact support |
Common Error Codes
| Code | Description |
|---|
| AGENT_NOT_FOUND | The specified agent ID does not exist |
| INVALID_CONFIGURATION | Agent configuration is missing required fields |
| CALL_IN_PROGRESS | Cannot modify agent while a call is active |
| PROVIDER_UNAVAILABLE | STT/TTS/LLM provider returned an error |
| VERSION_CONFLICT | Optimistic lock failure — refresh and retry |
| TOOL_EXECUTION_FAILED | MCP/API/Connector tool returned an error |
| RATE_LIMIT_EXCEEDED | Too many requests — see Retry-After header |
| TENANT_MISMATCH | Resource belongs to a different tenant |