@devries-cameron20 / composio Mirror · read-only / commits / 68444adea
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 12:00 UTC

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">