Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
refactor(docs): Simplify API errors page
Sushmithamallesh68444adead07
diff --git a/docs/content/reference/errors.mdx b/docs/content/reference/errors.mdxindex 328f20084..962942799 100644--- a/docs/content/reference/errors.mdx+++ b/docs/content/reference/errors.mdx@@ -3,136 +3,105 @@ title: API Errorsdescription: Understanding and handling Composio API errors----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.+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.## The error object```json{"error": {- "message": "Tool not found",- "code": 1800,- "status": 404,+ "message": "No connected account found for this user and toolkit",+ "status": 400,"request_id": "req_abc123def456",- "suggested_fix": "Check if the tool slug is correct"+ "suggested_fix": "Connect the user to the toolkit first"}}```### Attributes-<div className="[&_table]:text-sm">--| Attribute | Type | Description |-|-----------|------|-------------|-| `message` | string | A human-readable message providing details about the error. Use this to understand what went wrong. |-| `code` | integer | A Composio-specific error code for programmatic handling. See [error codes](#error-codes) below. |-| `status` | integer | The HTTP status code. |-| `request_id` | string | A unique identifier for this request. **Always include this when contacting support.** |-| `suggested_fix` | string, optional | Guidance on how to resolve the error, when available. |-| `errors` | array, optional | For validation errors, a list of specific issues with your request. |--</div>+| Attribute | Description |+|-----------|-------------|+| `message` | A human-readable message providing details about the error. |+| `status` | The HTTP status code. |+| `request_id` | A unique identifier for this request. Include this when contacting support. |+| `suggested_fix` | When available, guidance on how to resolve the error. |## HTTP status codes-<div className="[&_table]:text-sm">-| Status | Description ||--------|-------------|-| `200` | OK - Request succeeded |-| `400` | Bad Request - Invalid parameters or malformed request |-| `401` | Unauthorized - Invalid or missing API key |-| `403` | Forbidden - Valid key but insufficient permissions |-| `404` | Not Found - Resource doesn't exist |-| `409` | Conflict - Resource already exists |-| `410` | Gone - Resource was deleted |-| `422` | Unprocessable - Valid request but can't be processed |-| `429` | Too Many Requests - Rate limit exceeded |-| `500` | Server Error - Something went wrong on our end |+| `200 - OK` | Everything worked as expected. |+| `400 - Bad Request` | The request was unacceptable, often due to missing or invalid parameters. |+| `401 - Unauthorized` | No valid API key provided. |+| `403 - Forbidden` | The API key doesn't have permissions to perform the request. |+| `404 - Not Found` | The requested resource doesn't exist. |+| `409 - Conflict` | The request conflicts with another request. |+| `410 - Gone` | The requested resource has been deleted. |+| `422 - Unprocessable` | The request was valid but cannot be processed. |+| `429 - Too Many Requests` | Too many requests hit the API too quickly. |+| `500 - Server Error` | Something went wrong on Composio's end. |-</div>+## Error types-## Error codes+### Authentication errors-Composio uses numeric error codes grouped by domain. When handling errors programmatically, check both the HTTP status and the error code.+Errors related to API key validation and permissions.-### Authentication--| Code | Status | Message | Resolution |-|------|--------|---------|------------|-| `801` | 401 | Invalid API Key | Verify your key in [Settings](https://platform.composio.dev/settings) |-| `906` | 401 | No authentication provided | Include the `x-api-key` header |-| `904` | 403 | Invalid project access | Use the correct API key scope |+| Error | Cause |+|-------|-------|+| Invalid API key | The API key provided is incorrect or has been revoked. Verify your key in [Settings](https://platform.composio.dev/settings). |+| No authentication provided | The request is missing the `x-api-key` header. |+| Invalid project access | The API key doesn't have access to this resource. Check that you're using the correct key scope. |<Callout>-For auth issues, see [Authentication Troubleshooting](/docs/troubleshooting/authentication).+See [Authentication Troubleshooting](/docs/troubleshooting/authentication) for more help.</Callout>-### Tools+### Tool errors++Errors that occur when fetching or executing tools.-| Code | Status | Message | Resolution |-|------|--------|---------|------------|-| `1800` | 404 | Tool not found | Check tool slug - they're case-sensitive (`SCREAMING_SNAKE_CASE`) |-| `1801` | 500 | Tool execution failed | External service error - check parameters and permissions |-| `1803` | 400 | No connected account | User needs to [authenticate](/docs/authenticating-users) first |+| Error | Cause |+|-------|-------|+| Tool not found | The tool slug doesn't exist. Tool slugs are case-sensitive and use `SCREAMING_SNAKE_CASE`. |+| No connected account | The user hasn't connected to this toolkit yet. See [Authenticating Users](/docs/authenticating-users). |+| Tool execution failed | The external service returned an error. Check tool parameters and user permissions. |<Callout>-For tool issues, see [Tools Troubleshooting](/docs/troubleshooting/tools).+See [Tools Troubleshooting](/docs/troubleshooting/tools) for more help.</Callout>-### Connected accounts+### Connection errors++Errors related to connected accounts.-| Code | Status | Message | Resolution |-|------|--------|---------|------------|-| `606` | 404 | Connected account not found | Verify the `connectedAccountId` |-| `1205` | 422 | Auth refresh required | Prompt user to re-authenticate |-| `1806` | 410 | Connected account deleted | Create a new connection |+| Error | Cause |+|-------|-------|+| Connected account not found | The `connectedAccountId` doesn't exist or was deleted. |+| Auth refresh required | The OAuth token has expired. Prompt the user to re-authenticate. |+| Connected account deleted | The connection was removed. Create a new connection. |-### Triggers+### Trigger errors-| Code | Status | Message | Resolution |-|------|--------|---------|------------|-| `2601` | 404 | Trigger not found | Verify the trigger slug exists |-| `1202` | 410 | Trigger instance deleted | Create a new trigger instance |+Errors related to trigger subscriptions.++| Error | Cause |+|-------|-------|+| Trigger not found | The trigger slug doesn't exist for this toolkit. |+| Trigger instance deleted | The trigger subscription or its connected account was removed. |<Callout>-For trigger issues, see [Triggers Troubleshooting](/docs/troubleshooting/triggers).+See [Triggers Troubleshooting](/docs/troubleshooting/triggers) for more help.</Callout>-### Rate limits--| Code | Status | Message | Resolution |-|------|--------|---------|------------|-| `10429` | 429 | Rate limit exceeded | Implement exponential backoff |--When you receive a `429`, wait before retrying:--```typescript-async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {- for (let i = 0; i < maxRetries; i++) {- try {- return await fn();- } catch (err: any) {- if (err.status === 429 && i < maxRetries - 1) {- await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));- continue;- }- throw err;- }- }- throw new Error('Max retries exceeded');-}-```+## Rate limiting-## Getting help+When you hit rate limits, you'll receive a `429` status code. Back off exponentially and retry.-When contacting support, include:+## Getting help-- **Request ID** from the error response-- **Error code and message**-- **Timestamp** of when it occurred-- **What you were doing** (endpoint, parameters)+When contacting support, include the `request_id` from the error response.<Cards><Card title="Troubleshooting" href="/docs/troubleshooting">