Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

refactor(docs): Simplify API errors page

Sushmithamallesh68444adead07
diff --git a/docs/content/reference/errors.mdx b/docs/content/reference/errors.mdx
index 328f20084..962942799 100644
--- a/docs/content/reference/errors.mdx
+++ b/docs/content/reference/errors.mdx
@@ -3,136 +3,105 @@ title: API Errors
description: Understanding and handling Composio API errors
---
-Composio uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error with the information provided. Codes in the `5xx` range indicate an error with Composio's servers.
+Composio uses conventional HTTP response codes to indicate the success or failure of an API request. In general: codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error with the information provided, and codes in the `5xx` range indicate an error with Composio's servers.
## The error object
```json
{
"error": {
- "message": "Tool not found",
- "code": 1800,
- "status": 404,
+ "message": "No connected account found for this user and toolkit",
+ "status": 400,
"request_id": "req_abc123def456",
- "suggested_fix": "Check if the tool slug is correct"
+ "suggested_fix": "Connect the user to the toolkit first"
}
}
```
### Attributes
-<div className="[&_table]:text-sm">
-
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `message` | string | A human-readable message providing details about the error. Use this to understand what went wrong. |
-| `code` | integer | A Composio-specific error code for programmatic handling. See [error codes](#error-codes) below. |
-| `status` | integer | The HTTP status code. |
-| `request_id` | string | A unique identifier for this request. **Always include this when contacting support.** |
-| `suggested_fix` | string, optional | Guidance on how to resolve the error, when available. |
-| `errors` | array, optional | For validation errors, a list of specific issues with your request. |
-
-</div>
+| Attribute | Description |
+|-----------|-------------|
+| `message` | A human-readable message providing details about the error. |
+| `status` | The HTTP status code. |
+| `request_id` | A unique identifier for this request. Include this when contacting support. |
+| `suggested_fix` | When available, guidance on how to resolve the error. |
## HTTP status codes
-<div className="[&_table]:text-sm">
-
| Status | Description |
|--------|-------------|
-| `200` | OK - Request succeeded |
-| `400` | Bad Request - Invalid parameters or malformed request |
-| `401` | Unauthorized - Invalid or missing API key |
-| `403` | Forbidden - Valid key but insufficient permissions |
-| `404` | Not Found - Resource doesn't exist |
-| `409` | Conflict - Resource already exists |
-| `410` | Gone - Resource was deleted |
-| `422` | Unprocessable - Valid request but can't be processed |
-| `429` | Too Many Requests - Rate limit exceeded |
-| `500` | Server Error - Something went wrong on our end |
+| `200 - OK` | Everything worked as expected. |
+| `400 - Bad Request` | The request was unacceptable, often due to missing or invalid parameters. |
+| `401 - Unauthorized` | No valid API key provided. |
+| `403 - Forbidden` | The API key doesn't have permissions to perform the request. |
+| `404 - Not Found` | The requested resource doesn't exist. |
+| `409 - Conflict` | The request conflicts with another request. |
+| `410 - Gone` | The requested resource has been deleted. |
+| `422 - Unprocessable` | The request was valid but cannot be processed. |
+| `429 - Too Many Requests` | Too many requests hit the API too quickly. |
+| `500 - Server Error` | Something went wrong on Composio's end. |
-</div>
+## Error types
-## Error codes
+### Authentication errors
-Composio uses numeric error codes grouped by domain. When handling errors programmatically, check both the HTTP status and the error code.
+Errors related to API key validation and permissions.
-### Authentication
-
-| Code | Status | Message | Resolution |
-|------|--------|---------|------------|
-| `801` | 401 | Invalid API Key | Verify your key in [Settings](https://platform.composio.dev/settings) |
-| `906` | 401 | No authentication provided | Include the `x-api-key` header |
-| `904` | 403 | Invalid project access | Use the correct API key scope |
+| Error | Cause |
+|-------|-------|
+| Invalid API key | The API key provided is incorrect or has been revoked. Verify your key in [Settings](https://platform.composio.dev/settings). |
+| No authentication provided | The request is missing the `x-api-key` header. |
+| Invalid project access | The API key doesn't have access to this resource. Check that you're using the correct key scope. |
<Callout>
-For auth issues, see [Authentication Troubleshooting](/docs/troubleshooting/authentication).
+See [Authentication Troubleshooting](/docs/troubleshooting/authentication) for more help.
</Callout>
-### Tools
+### Tool errors
+
+Errors that occur when fetching or executing tools.
-| Code | Status | Message | Resolution |
-|------|--------|---------|------------|
-| `1800` | 404 | Tool not found | Check tool slug - they're case-sensitive (`SCREAMING_SNAKE_CASE`) |
-| `1801` | 500 | Tool execution failed | External service error - check parameters and permissions |
-| `1803` | 400 | No connected account | User needs to [authenticate](/docs/authenticating-users) first |
+| Error | Cause |
+|-------|-------|
+| Tool not found | The tool slug doesn't exist. Tool slugs are case-sensitive and use `SCREAMING_SNAKE_CASE`. |
+| No connected account | The user hasn't connected to this toolkit yet. See [Authenticating Users](/docs/authenticating-users). |
+| Tool execution failed | The external service returned an error. Check tool parameters and user permissions. |
<Callout>
-For tool issues, see [Tools Troubleshooting](/docs/troubleshooting/tools).
+See [Tools Troubleshooting](/docs/troubleshooting/tools) for more help.
</Callout>
-### Connected accounts
+### Connection errors
+
+Errors related to connected accounts.
-| Code | Status | Message | Resolution |
-|------|--------|---------|------------|
-| `606` | 404 | Connected account not found | Verify the `connectedAccountId` |
-| `1205` | 422 | Auth refresh required | Prompt user to re-authenticate |
-| `1806` | 410 | Connected account deleted | Create a new connection |
+| Error | Cause |
+|-------|-------|
+| Connected account not found | The `connectedAccountId` doesn't exist or was deleted. |
+| Auth refresh required | The OAuth token has expired. Prompt the user to re-authenticate. |
+| Connected account deleted | The connection was removed. Create a new connection. |
-### Triggers
+### Trigger errors
-| Code | Status | Message | Resolution |
-|------|--------|---------|------------|
-| `2601` | 404 | Trigger not found | Verify the trigger slug exists |
-| `1202` | 410 | Trigger instance deleted | Create a new trigger instance |
+Errors related to trigger subscriptions.
+
+| Error | Cause |
+|-------|-------|
+| Trigger not found | The trigger slug doesn't exist for this toolkit. |
+| Trigger instance deleted | The trigger subscription or its connected account was removed. |
<Callout>
-For trigger issues, see [Triggers Troubleshooting](/docs/troubleshooting/triggers).
+See [Triggers Troubleshooting](/docs/troubleshooting/triggers) for more help.
</Callout>
-### Rate limits
-
-| Code | Status | Message | Resolution |
-|------|--------|---------|------------|
-| `10429` | 429 | Rate limit exceeded | Implement exponential backoff |
-
-When you receive a `429`, wait before retrying:
-
-```typescript
-async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
- for (let i = 0; i < maxRetries; i++) {
- try {
- return await fn();
- } catch (err: any) {
- if (err.status === 429 && i < maxRetries - 1) {
- await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
- continue;
- }
- throw err;
- }
- }
- throw new Error('Max retries exceeded');
-}
-```
+## Rate limiting
-## Getting help
+When you hit rate limits, you'll receive a `429` status code. Back off exponentially and retry.
-When contacting support, include:
+## Getting help
-- **Request ID** from the error response
-- **Error code and message**
-- **Timestamp** of when it occurred
-- **What you were doing** (endpoint, parameters)
+When contacting support, include the `request_id` from the error response.
<Cards>
<Card title="Troubleshooting" href="/docs/troubleshooting">