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
- Remove internal error codes (not useful to users) - Remove retry code example - Focus on what users care about: error messages and how to fix them - Follow Stripe's clean, focused documentation style Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sushmithamallesh committed
Jan 28, 2026 at 12:54 UTC
68444adead07bd5bdae0e2ede40d8f3ac72862e8
1 file changed
+58
-89
docs/content/reference/errors.mdx
+58
-89
@@ -3,136 +3,105 @@ title: API Errors
3
description: Understanding and handling Composio API errors
4
---
5
6
-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.
6
+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.
7
8
## The error object
9
10
```json
11
{
12
"error": {
13
- "message": "Tool not found",
14
- "code": 1800,
15
- "status": 404,
13
+ "message": "No connected account found for this user and toolkit",
14
+ "status": 400,
15
"request_id": "req_abc123def456",
17
- "suggested_fix": "Check if the tool slug is correct"
16
+ "suggested_fix": "Connect the user to the toolkit first"
17
}
18
}
19
```
20
21
### Attributes
22
24
-<div className="[&_table]:text-sm">
25
-
26
-| Attribute | Type | Description |
27
-|-----------|------|-------------|
28
-| `message` | string | A human-readable message providing details about the error. Use this to understand what went wrong. |
29
-| `code` | integer | A Composio-specific error code for programmatic handling. See [error codes](#error-codes) below. |
30
-| `status` | integer | The HTTP status code. |
31
-| `request_id` | string | A unique identifier for this request. **Always include this when contacting support.** |
32
-| `suggested_fix` | string, optional | Guidance on how to resolve the error, when available. |
33
-| `errors` | array, optional | For validation errors, a list of specific issues with your request. |
34
-
35
-</div>
23
+| Attribute | Description |
24
+|-----------|-------------|
25
+| `message` | A human-readable message providing details about the error. |
26
+| `status` | The HTTP status code. |
27
+| `request_id` | A unique identifier for this request. Include this when contacting support. |
28
+| `suggested_fix` | When available, guidance on how to resolve the error. |
29
30
## HTTP status codes
31
39
-<div className="[&_table]:text-sm">
40
-
32
| Status | Description |
33
|--------|-------------|
43
-| `200` | OK - Request succeeded |
44
-| `400` | Bad Request - Invalid parameters or malformed request |
45
-| `401` | Unauthorized - Invalid or missing API key |
46
-| `403` | Forbidden - Valid key but insufficient permissions |
47
-| `404` | Not Found - Resource doesn't exist |
48
-| `409` | Conflict - Resource already exists |
49
-| `410` | Gone - Resource was deleted |
50
-| `422` | Unprocessable - Valid request but can't be processed |
51
-| `429` | Too Many Requests - Rate limit exceeded |
52
-| `500` | Server Error - Something went wrong on our end |
34
+| `200 - OK` | Everything worked as expected. |
35
+| `400 - Bad Request` | The request was unacceptable, often due to missing or invalid parameters. |
36
+| `401 - Unauthorized` | No valid API key provided. |
37
+| `403 - Forbidden` | The API key doesn't have permissions to perform the request. |
38
+| `404 - Not Found` | The requested resource doesn't exist. |
39
+| `409 - Conflict` | The request conflicts with another request. |
40
+| `410 - Gone` | The requested resource has been deleted. |
41
+| `422 - Unprocessable` | The request was valid but cannot be processed. |
42
+| `429 - Too Many Requests` | Too many requests hit the API too quickly. |
43
+| `500 - Server Error` | Something went wrong on Composio's end. |
44
54
-</div>
45
+## Error types
46
56
-## Error codes
47
+### Authentication errors
48
58
-Composio uses numeric error codes grouped by domain. When handling errors programmatically, check both the HTTP status and the error code.
49
+Errors related to API key validation and permissions.
50
60
-### Authentication
61
-
62
-| Code | Status | Message | Resolution |
63
-|------|--------|---------|------------|
64
-| `801` | 401 | Invalid API Key | Verify your key in [Settings](https://platform.composio.dev/settings) |
65
-| `906` | 401 | No authentication provided | Include the `x-api-key` header |
66
-| `904` | 403 | Invalid project access | Use the correct API key scope |
51
+| Error | Cause |
52
+|-------|-------|
53
+| Invalid API key | The API key provided is incorrect or has been revoked. Verify your key in [Settings](https://platform.composio.dev/settings). |
54
+| No authentication provided | The request is missing the `x-api-key` header. |
55
+| Invalid project access | The API key doesn't have access to this resource. Check that you're using the correct key scope. |
56
57
<Callout>
69
-For auth issues, see [Authentication Troubleshooting](/docs/troubleshooting/authentication).
58
+See [Authentication Troubleshooting](/docs/troubleshooting/authentication) for more help.
59
</Callout>
60
72
-### Tools
61
+### Tool errors
62
+
63
+Errors that occur when fetching or executing tools.
64
74
-| Code | Status | Message | Resolution |
75
-|------|--------|---------|------------|
76
-| `1800` | 404 | Tool not found | Check tool slug - they're case-sensitive (`SCREAMING_SNAKE_CASE`) |
77
-| `1801` | 500 | Tool execution failed | External service error - check parameters and permissions |
78
-| `1803` | 400 | No connected account | User needs to [authenticate](/docs/authenticating-users) first |
65
+| Error | Cause |
66
+|-------|-------|
67
+| Tool not found | The tool slug doesn't exist. Tool slugs are case-sensitive and use `SCREAMING_SNAKE_CASE`. |
68
+| No connected account | The user hasn't connected to this toolkit yet. See [Authenticating Users](/docs/authenticating-users). |
69
+| Tool execution failed | The external service returned an error. Check tool parameters and user permissions. |
70
71
<Callout>
81
-For tool issues, see [Tools Troubleshooting](/docs/troubleshooting/tools).
72
+See [Tools Troubleshooting](/docs/troubleshooting/tools) for more help.
73
</Callout>
74
84
-### Connected accounts
75
+### Connection errors
76
+
77
+Errors related to connected accounts.
78
86
-| Code | Status | Message | Resolution |
87
-|------|--------|---------|------------|
88
-| `606` | 404 | Connected account not found | Verify the `connectedAccountId` |
89
-| `1205` | 422 | Auth refresh required | Prompt user to re-authenticate |
90
-| `1806` | 410 | Connected account deleted | Create a new connection |
79
+| Error | Cause |
80
+|-------|-------|
81
+| Connected account not found | The `connectedAccountId` doesn't exist or was deleted. |
82
+| Auth refresh required | The OAuth token has expired. Prompt the user to re-authenticate. |
83
+| Connected account deleted | The connection was removed. Create a new connection. |
84
92
-### Triggers
85
+### Trigger errors
86
94
-| Code | Status | Message | Resolution |
95
-|------|--------|---------|------------|
96
-| `2601` | 404 | Trigger not found | Verify the trigger slug exists |
97
-| `1202` | 410 | Trigger instance deleted | Create a new trigger instance |
87
+Errors related to trigger subscriptions.
88
+
89
+| Error | Cause |
90
+|-------|-------|
91
+| Trigger not found | The trigger slug doesn't exist for this toolkit. |
92
+| Trigger instance deleted | The trigger subscription or its connected account was removed. |
93
94
<Callout>
100
-For trigger issues, see [Triggers Troubleshooting](/docs/troubleshooting/triggers).
95
+See [Triggers Troubleshooting](/docs/troubleshooting/triggers) for more help.
96
</Callout>
97
103
-### Rate limits
104
-
105
-| Code | Status | Message | Resolution |
106
-|------|--------|---------|------------|
107
-| `10429` | 429 | Rate limit exceeded | Implement exponential backoff |
108
-
109
-When you receive a `429`, wait before retrying:
110
-
111
-```typescript
112
-async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
113
- for (let i = 0; i < maxRetries; i++) {
114
- try {
115
- return await fn();
116
- } catch (err: any) {
117
- if (err.status === 429 && i < maxRetries - 1) {
118
- await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
119
- continue;
120
- }
121
- throw err;
122
- }
123
- }
124
- throw new Error('Max retries exceeded');
125
-}
126
-```
98
+## Rate limiting
99
128
-## Getting help
100
+When you hit rate limits, you'll receive a `429` status code. Back off exponentially and retry.
101
130
-When contacting support, include:
102
+## Getting help
103
132
-- **Request ID** from the error response
133
-- **Error code and message**
134
-- **Timestamp** of when it occurred
135
-- **What you were doing** (endpoint, parameters)
104
+When contacting support, include the `request_id` from the error response.
105
106
<Cards>
107
<Card title="Troubleshooting" href="/docs/troubleshooting">