Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
feat(docs): Add API errors reference page
- Add comprehensive API errors documentation with error codes, HTTP status codes, and resolutions - Cross-reference from troubleshooting pages - Follow Stripe-style documentation approach with tables for error codes Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sushmithamallesh committed
Jan 28, 2026 at 12:45 UTC
913f56f96197b885d9ff3da781d09379c566ef25
4 files changed
+162
-1
docs/content/docs/troubleshooting/api.mdx
+4
@@ -3,6 +3,10 @@ title: API
3
description: Troubleshooting API issues
4
---
5
6
+<Callout>
7
+For a complete list of error codes and their meanings, see [API Errors Reference](/reference/errors).
8
+</Callout>
9
+
10
## Reporting API issues
11
12
When reporting API issues to support, provide the following:
docs/content/docs/troubleshooting/index.mdx
+7
-1
@@ -3,12 +3,18 @@ title: Troubleshooting
3
description: Common issues and quick links
4
---
5
6
-import { Bug, Brain, Sparkles, MessageCircle, MessageSquare, BookOpen } from 'lucide-react';
6
+import { Bug, Brain, Sparkles, MessageCircle, MessageSquare, BookOpen, AlertCircle } from 'lucide-react';
7
8
This section is designed to help you quickly identify and resolve common issues encountered with Composio.
9
10
Some quick links:
11
12
+<Cards>
13
+ <Card title="API Errors Reference" href="/reference/errors" icon={<AlertCircle />}>
14
+ HTTP status codes, error codes, and how to resolve common API errors.
15
+ </Card>
16
+</Cards>
17
+
18
<Cards>
19
<Card title="Report issues" href="https://github.com/ComposioHQ/composio/issues/new?labels=bug" icon={<Bug />}>
20
Found a bug? Please create a Github issue!
docs/content/reference/errors.mdx
new
+150
@@ -0,0 +1,150 @@
1
+---
2
+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.
7
+
8
+## The error object
9
+
10
+```json
11
+{
12
+ "error": {
13
+ "message": "Tool not found",
14
+ "code": 1800,
15
+ "status": 404,
16
+ "request_id": "req_abc123def456",
17
+ "suggested_fix": "Check if the tool slug is correct"
18
+ }
19
+}
20
+```
21
+
22
+### Attributes
23
+
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>
36
+
37
+## HTTP status codes
38
+
39
+<div className="[&_table]:text-sm">
40
+
41
+| Status | Description |
42
+|--------|-------------|
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 |
53
+
54
+</div>
55
+
56
+## Error codes
57
+
58
+Composio uses numeric error codes grouped by domain. When handling errors programmatically, check both the HTTP status and the error code.
59
+
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 |
67
+
68
+<Callout>
69
+For auth issues, see [Authentication Troubleshooting](/docs/troubleshooting/authentication).
70
+</Callout>
71
+
72
+### Tools
73
+
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 |
79
+
80
+<Callout>
81
+For tool issues, see [Tools Troubleshooting](/docs/troubleshooting/tools).
82
+</Callout>
83
+
84
+### Connected accounts
85
+
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 |
91
+
92
+### Triggers
93
+
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 |
98
+
99
+<Callout>
100
+For trigger issues, see [Triggers Troubleshooting](/docs/troubleshooting/triggers).
101
+</Callout>
102
+
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
+```
127
+
128
+## Getting help
129
+
130
+When contacting support, include:
131
+
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)
136
+
137
+<Cards>
138
+ <Card title="Troubleshooting" href="/docs/troubleshooting">
139
+ Common issues and solutions
140
+ </Card>
141
+ <Card title="Discord" href="https://discord.com/channels/1170785031560646836/1268871288156323901">
142
+ Community support
143
+ </Card>
144
+ <Card title="Email" href="mailto:support@composio.dev">
145
+ Contact support team
146
+ </Card>
147
+ <Card title="GitHub" href="https://github.com/ComposioHQ/composio/issues/new?labels=bug">
148
+ Report a bug
149
+ </Card>
150
+</Cards>
docs/content/reference/meta.json
+1
@@ -2,6 +2,7 @@
2
"title": "Reference",
3
"pages": [
4
"index",
5
+ "errors",
6
"api-reference",
7
"sdk-reference"
8
]