***

## title: Errors

### Overview of errors you might encounter

| Status Code | Meaning               | Action                           |
| ----------- | --------------------- | -------------------------------- |
| 200         | Success               | Request completed successfully   |
| 400         | Bad Request           | Check request parameters         |
| 401         | Unauthorized          | Verify API key is valid          |
| 403         | Forbidden             | Check API key scopes/permissions |
| 404         | Not Found             | Agent/resource doesn't exist     |
| 429         | Too Many Requests     | Implement backoff and retry      |
| 500         | Internal Server Error | Contact support if persistent    |

### In-depth

| HTTP | Code                                                    | When it happens                                                                                                                                                                                                      |
| ---- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401  | `bad_request`                                           | This can happen for a missing API key: `{"detail": "API key is required"}`, an invalid/expired API key: `{"detail": "Invalid or expired API key"}` or for other auth parsing errors: `{"detail": "<error message>"}` |
| 403  | `forbidden`                                             | API key lacks scope for the path (example: `/v1/contents`): `{"detail": "Missing required scopes"}`                                                                                                                  |
| 404  | `agent_not_found` or `agent_not_supported_yet`          | The agent ID does not exist (or was deleted), or the agent uses an unsupported model/feature                                                                                                                         |
| 500  | `Internal Server Error (auth/authorization middleware)` | This can happen in the case of authentication failure: `{"detail": "Internal authentication error"}` or authorization failure: `{"detail": "Internal authorization error"}`                                          |