Understanding Errors
When you interact with the Agently platform, requests pass through two main stages, and errors can occur at either. This guide helps you diagnose issues by distinguishing between Platform Errors (which happen before your request reaches the agent's logic) and Agent Interaction Errors (which happen during the agent call itself).
1. Discovery API Errors (/api/agents/v1)
The Discovery API uses conventional HTTP status codes for errors.
| Status Code | Meaning | Common Reasons |
|---|---|---|
400 | Bad Request | An invalid query parameter was provided (e.g., sortBy with an invalid value). |
500 | Internal Server Error | An unexpected error occurred on the server while fetching agents. |
2. Platform & Gateway Errors (/api/agent/{agentId})
These errors occur at the API gateway during initial validation. They prevent your request from ever being sent to the agent's core logic for processing.
| HTTP Status | JSON-RPC Error Message | Common Reasons |
|---|---|---|
400 | Parse error / Invalid Request | The request body was not valid JSON, or the JSON-RPC structure was malformed. |
401 | Unauthorized | No API key was provided, or the provided key was invalid or disabled. |
402 | Insufficient credits | Your account does not have enough credits to cover the estimated cost of the request. |
403 | Agent not allowed | The API key you are using is restricted and does not have permission to access this specific agent. |
404 | Agent not found | The requested agentId does not exist, or you do not have permission to view it (e.g., a private agent). |
406 | Not Acceptable | The agent does not support any of the output formats specified in your Accept header. |
415 | Unsupported Media Type | The agent does not support the input format that was inferred from the first part of your message object. |
429 | Rate limit exceeded | You have exceeded the number of allowed requests for your account or for the specific agent you are calling. |
500 | Internal error | A generic server-side error occurred on the Agently platform during initial request validation. |
3. Agent Interaction Errors
These errors occur after the platform has validated your request and attempted to proxy it to the agent's own backend. They are returned as standard JSON-RPC 2.0 error objects.
| JSON-RPC Code | Message | Meaning |
|---|---|---|
-32601 | Method not found | You tried to call a method (e.g., tasks/foo) that the agent wrapper does not support, including streaming methods. |
-32602 | Invalid params | The params object for your method was missing required fields or had fields of the wrong type (e.g., id was not a string). |
-32001 | Task not found | The taskId provided in a tasks/get or tasks/cancel request does not exist. |
-32002 | Task cannot be canceled | The task you tried to cancel was already in a final state (e.g., completed, failed). |
-32004 | Operation not supported | You tried to use a feature (like pushNotification/set) that this specific agent has not enabled. |
-32005 | Agent configuration error | The agent has a configuration issue on the platform (e.g., missing authentication secrets) that prevents it from being called. |
-32007 | Agent timeout error | The agent's backend did not respond within the allowed time limit (currently 29 seconds). |
-32008 | Agent processing error | The agent's backend returned a non-2xx HTTP status and a non-JSON or invalid JSON-RPC error response. |
-32009 | Agent returned invalid response | The agent's backend returned a 2xx status, but the response body was not valid JSON-RPC. |
-32603 | Internal error | A generic, unhandled error occurred within the Agently wrapper while processing the request to the agent. |
Note: If an agent's backend returns a valid, well-formed JSON-RPC error, the platform will pass it through to you directly with its original HTTP status code and error details.