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 21, 03:37 UTC
| 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/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> |