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

next
mdx 119 lines 4.53 KB
Raw
1 ---
2 title: Errors
3 description: Composio API error codes, HTTP status codes, and troubleshooting guide
4 keywords: [API errors, error codes, HTTP status codes, error handling, troubleshooting, "400 bad request", "401 unauthorized", "429 rate limit"]
5 ---
6
7 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.
8
9 ## The error object
10
11 ```json
12 {
13 "error": {
14 "message": "No connected account found for this user and toolkit",
15 "status": 400,
16 "request_id": "req_abc123def456",
17 "suggested_fix": "Connect the user to the toolkit first"
18 }
19 }
20 ```
21
22 ### Attributes
23
24 | Attribute | Description |
25 |-----------|-------------|
26 | `message` | A human-readable message providing details about the error. |
27 | `status` | The HTTP status code. |
28 | `request_id` | A unique identifier for this request. Include this when contacting support. |
29 | `suggested_fix` | When available, guidance on how to resolve the error. |
30
31 ## HTTP status codes
32
33 | Code | Status | Description |
34 |------|--------|-------------|
35 | 200 | OK | Everything worked as expected. |
36 | 400 | Bad Request | The request was unacceptable, often due to missing a required parameter. |
37 | 401 | Unauthorized | No valid API key provided. |
38 | 403 | Forbidden | The API key doesn't have permissions to perform the request. |
39 | 404 | Not Found | The requested resource doesn't exist. |
40 | 409 | Conflict | The request conflicts with another request (perhaps due to using the same idempotent key). |
41 | 422 | Unprocessable Entity | The request was valid but cannot be processed. |
42 | 429 | Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |
43 | 500, 502, 503, 504 | Server Errors | Something went wrong on Composio's end. |
44
45 ## Error types
46
47 ### Authentication errors
48
49 Composio uses two types of API keys:
50 - **Project API key** (`x-api-key`) — For project-level operations
51 - **Organization API key** (`x-org-api-key`) — For organization-level access across projects
52
53 | Error | Cause |
54 |-------|-------|
55 | Invalid API key | The API key is incorrect or revoked. Verify in [Settings](https://dashboard.composio.dev/~/project/settings/api-keys). |
56 | No authentication provided | The request is missing the `x-api-key` or `x-org-api-key` header. |
57 | Invalid organization key | The organization API key is incorrect or revoked. Verify in Organization Settings. |
58 | Insufficient permissions | The API key doesn't have access to this resource. |
59
60 <Callout>
61 See [Authenticating users](/docs/authentication) for more help.
62 </Callout>
63
64 ### Tool errors
65
66 Errors that occur when fetching or executing tools.
67
68 | Error | Cause |
69 |-------|-------|
70 | Tool not found | The tool slug doesn't exist. Tool slugs are case-sensitive and use `SCREAMING_SNAKE_CASE`. |
71 | No connected account | The user hasn't connected to this toolkit yet. |
72 | Tool execution failed | The external service returned an error. Check tool parameters and user permissions. |
73
74 <Callout>
75 See [Tools and toolkits](/docs/how-composio-works) for more help.
76 </Callout>
77
78 ### Connection errors
79
80 Errors related to connected accounts.
81
82 | Error | Cause |
83 |-------|-------|
84 | Connected account not found | The `connectedAccountId` doesn't exist or was deleted. |
85 | Auth refresh required | The OAuth token has expired. Prompt the user to re-authenticate. |
86 | Connected account deleted | The connection was removed. Create a new connection. |
87
88 ### Trigger errors
89
90 Errors related to trigger subscriptions.
91
92 | Error | Cause |
93 |-------|-------|
94 | Trigger not found | The trigger slug doesn't exist for this toolkit. |
95 | Trigger instance deleted | The trigger subscription or its connected account was removed. |
96
97 <Callout>
98 See [Triggers](/docs/triggers) for more help.
99 </Callout>
100
101 ## Rate limiting
102
103 When you hit rate limits, you'll receive a `429` status code. See [Rate Limits](/reference/v3/rate-limits) for details on limits by plan and best practices for handling rate limit errors.
104
105 ## Getting help
106
107 When contacting support, include the `request_id` from the error response.
108
109 <Cards>
110 <Card title="Discord" href="https://discord.com/channels/1170785031560646836/1268871288156323901">
111 Community support
112 </Card>
113 <Card title="Email" href="mailto:support@composio.dev">
114 Contact support team
115 </Card>
116 <Card title="GitHub" href="https://github.com/ComposioHQ/composio/issues/new?labels=bug">
117 Report a bug
118 </Card>
119 </Cards>