@devries-cameron20 / composio Mirror · read-only / commits / 913f56f96
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

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 ]