Composio Error Codes Documentation - ComposioHQ/helm-charts GitHub Wiki

This document provides a comprehensive reference for all error codes returned by the Composio platform APIs.

Error Response Format

All API errors follow this standard format:

{
  "error": {
    "message": "Human-readable error description",
    "code": 1234,
    "status": 400,
    "request_id": "req_abc123",
    "suggested_fix": "Optional suggestion for resolving the error",
    "errors": ["Additional validation errors if applicable"]
  }
}

Error Code Ranges

  • 100-199: Prisma/Database errors
  • 200-299: Auth_Config errors
  • 300-399: Toolkit errors
  • 400-499: SecurityProvider errors
  • 500-599: MCP errors
  • 600-699: ConnectedAccount errors
  • 700-799: Redis errors
  • 800-899: APIKey errors
  • 900-999: Auth errors
  • 1000-1099: Email errors
  • 1100-1199: Pusher errors
  • 1200-1299: TriggerInstance errors
  • 1300-1399: JWT errors
  • 1500-1599: Stripe errors
  • 1600-1699: Thermos errors
  • 1700-1799: Tool_Auth errors
  • 1800-1899: ActionExecute errors
  • 1900-1999: ToolsList errors
  • 2000-2099: TeamMembers errors
  • 2100-2199: CLI errors
  • 2200-2299: Organization errors
  • 2300-2399: Labs errors
  • 2400-2499: Tool errors
  • 2500-2599: CustomToolkit errors
  • 2600-2699: Trigger errors
  • 2700-2799: OrgStripeMapping errors
  • 2800-2899: ExternalProxy errors
  • 3000-3099: Axios errors
  • 3100-3199: TriggerRefresh errors
  • 3200-3299: OrgMember errors
  • 3300-3399: OrgApiKey errors
  • 3400-3499: UserOrgMapping errors
  • 3500-3599: OrgInviteCode errors
  • 3600-3699: MagicLink errors
  • 3700-3799: ComposioTools errors
  • 3800-3899: DebugLogs errors
  • 3900-3999: ProjectFiles errors
  • 4000-4099: Recipe errors
  • 4100-4199: Sandbox errors
  • 10000-10999: HTTP errors

Error Codes by Service

HTTP Errors (10000-10999)

Code Name Status Description
10400 BadRequest 400 Invalid request format or parameters
10401 Unauthorized 401 Authentication required
10403 Forbidden 403 Access denied
10404 URLNotFound 404 Requested URL not found
10410 Gone 410 Resource no longer available
10424 ResourceNotFound 404 Requested resource not found
10429 TooManyRequests 429 Rate limit exceeded
10500 InternalServerError 500 Internal server error
10501 NotImplemented 501 Feature not implemented
10502 Unreachable 500 Service unreachable
10503 ServiceUnavailable 503 Service temporarily unavailable
10503 BadState 422 Invalid system state

Auth Errors (900-999)

Code Name Status Description
900 BadRequest 400 Invalid authentication request
901 InternalServerError 500 Authentication service error
902 Unauthorized 401 Invalid credentials
903 NoCookie 401 Authentication cookie missing
904 InvalidProjectAccess 401 Insufficient project permissions
905 ValidationError 400 Authentication validation failed
906 NoAuthProvided 401 No authentication provided
907 OrgDeleted 401 Organization has been deleted
908 ProjectAPIKeyNotAllowed 401 Project API key not allowed for this endpoint

Prisma/Database Errors (100-199)

Code Name Status Description
100 BadRequest 400 Invalid database request
101 InternalServerError 500 Database internal error
102 UnknownError 500 Unknown database error
103 ResourceNotFound 400 Database record not found
104 AlreadyExists 400 Record already exists

Auth_Config Errors (200-299)

Code Name Status Description
300 BadRequest 400 Invalid auth config request
301 ValidationError 400 Auth config validation failed
302 NotFound 400 Auth config not found
303 NoAuthApp 400 No auth app configured
304 InternalServerError 500 Auth config service error

Toolkit Errors (300-399)

Code Name Status Description
400 ToolkitNotEnabled 400 Toolkit is not enabled
401 ToolkitNotFound 400 Toolkit not found
402 InternalServerError 500 Toolkit service error

SecurityProvider Errors (400-499)

Code Name Status Description
500 BadRequest 400 Invalid security provider request
501 EncryptionError 500 Encryption operation failed
502 DecryptionError 500 Decryption operation failed
503 SigningError 500 Digital signing failed

MCP Errors (500-599)

Code Name Status Description
1141 AuthConfigNotFound 400 MCP auth config not found
1142 ValidationError 403 MCP validation failed
1143 ResourceNotFound 404 MCP resource not found
1144 PartnerAlreadyExists 400 MCP partner already exists
1145 ServerInstanceNotFound 404 MCP server instance not found
1146 InternalServerError 500 MCP service error

ConnectedAccount Errors (600-699)

Code Name Status Description
600 BadRequest 400 Invalid connected account request
601 InternalServerError 500 Connected account service error
602 InvalidAuthScheme 400 Invalid authentication scheme
603 InvalidAppSchema 400 Invalid app schema
604 OAuth1RequestTokenError 500 OAuth1 request token error
605 JwtTokenError 400 JWT token error
606 ResourceNotFound 404 Connected account not found
607 CreateBadRequest 400 Invalid create request
608 ValidationError 400 Connected account validation failed
609 NoAuthApp 400 No auth app configured

Redis Errors (700-799)

Code Name Status Description
700 InternalServerError 500 Redis service error
701 NotFound 400 Redis key not found

APIKey Errors (800-899)

Code Name Status Description
800 ValidationError 400 API key validation failed
801 InvalidAPIKey 400 Invalid API key
802 Unauthorized 401 API key unauthorized
803 CannotFetchAPIKeys 400 Cannot fetch API keys
804 NoAPIKeysFound 400 No API keys found
805 UnableToDeleteAPIKeys 400 Cannot delete API keys
806 UnableToCreateAPIKey 400 Cannot create API key
807 UnableToDeleteAPIKey 400 Cannot delete API key
808 InvalidProjectAccess 401 Invalid project access
809 InternalServerError 500 API key service error

Email Errors (1000-1099)

Code Name Status Description
1000 FailedToSendEmail 500 Email sending failed
1001 EMAIL_NOT_AVAILABLE 400 Email service not available

Pusher Errors (1100-1199)

Code Name Status Description
1100 InternalServerError 500 Pusher service error
1101 InvalidChannelName 400 Invalid Pusher channel name

TriggerInstance Errors (1200-1299)

Code Name Status Description
1200 BadRequest 400 Invalid trigger instance request
1201 InternalServerError 500 Trigger instance service error
1202 TriggerInstanceGone 410 Trigger instance no longer available
1203 ResourceNotFound 404 Trigger instance not found
1204 ResourceAlreadyExists 409 Trigger instance already exists
1205 AuthRefreshRequired 422 Authentication refresh required
1206 ConflictedStatus 409 Conflicting trigger instance status

Project Errors (1800-1899)

Code Name Status Description
1800 BadRequest 400 Invalid project request
1801 InternalServerError 500 Project service error
1802 ProjectGone 410 Project no longer available
1803 ResourceNotFound 400 Project resource not found
1804 ResourceAlreadyExists 409 Project resource already exists

JWT Errors (1300-1399)

Code Name Status Description
1300 UnableToVerifyToken 500 JWT token verification failed
1301 InvalidToken 400 Invalid JWT token

Stripe Errors (1500-1599)

Code Name Status Description
1500 UserOrganisationNotFoundError 400 Stripe user organization not found

Thermos Errors (1600-1699)

Code Name Status Description
1600 BadRequest 400 Invalid Thermos request
1601 InternalServerError 500 Thermos service error
1602 ServiceUnavailable 500 Thermos service unavailable
1603 NotFound 404 Thermos resource not found
1604 Conflict 409 Thermos resource conflict

Tool_Auth Errors (1700-1799)

Code Name Status Description
1700 BadState 422 Invalid tool auth state
1701 NotImplemented 501 Tool auth feature not implemented
1702 BadRequest 400 Invalid tool auth request
1703 Unreachable 500 Tool auth service unreachable
1704 BadCallbackState 422 Invalid callback state
1705 FailedOauth2TokenExchange 500 OAuth2 token exchange failed
1706 BadConnectedAccountState 422 Invalid connected account state
1707 ResourceNotFound 400 Tool auth resource not found

ActionExecute Errors (1800-1899)

Code Name Status Description
1800 ToolNotFound 404 Action execution tool not found
1801 ExecutionError 500 Action execution failed
1802 Unauthorized 401 Action execution unauthorized
1803 ConnectedAccountError 400 Connected account error during execution
1804 FailedToGetAuthorization 500 Failed to get authorization for execution
1805 NoAPIKeyFound 400 No API key found for execution
1806 ConnectedAccountGone 410 Connected account no longer available

ToolsList Errors (1900-1999)

Code Name Status Description
1900 ThermosError 500 Thermos error in tools list
1901 CursorError 400 Cursor error in tools list
1902 ToolkitNotFound 404 Toolkit not found in tools list
1903 PassedToolsFromDifferentApp 400 Tools from different apps passed
1904 AuthConfigNotFound 400 Auth config not found for tools list

TeamMembers Errors (2000-2099)

Code Name Status Description
2000 MemberNotFound 400 Team member not found
2001 MemberAlreadyExists 400 Team member already exists

CLI Errors (2100-2199)

Code Name Status Description
2100 SessionNotFound 404 CLI session not found
2101 UserNotFound 404 CLI user not found

Organization Errors (2200-2299)

Code Name Status Description
2200 ResourceNotFound 404 Organization resource not found
2201 BadRequest 400 Invalid organization request
2202 InternalServerError 500 Organization service error

Labs Errors (2300-2399)

Code Name Status Description
2300 ExternalServiceError 500 External service error in Labs
2301 ToolNotFound 404 Tool not found in Labs
2302 AnalysisError 500 Analysis error in Labs
2303 InternalServerError 500 Labs service error

Tool Errors (2400-2499)

Code Name Status Description
2400 BadRequest 400 Invalid tool request
2401 ToolNotFound 404 Tool not found
2402 InternalServerError 500 Tool service error

CustomToolkit Errors (2500-2599)

Code Name Status Description
2500 BadRequest 400 Invalid custom toolkit request
2501 ResourceNotFound 404 Custom toolkit resource not found
2502 InternalServerError 500 Custom toolkit service error
2503 ResourceAlreadyExists 409 Custom toolkit resource already exists

Trigger Errors (2600-2699)

Code Name Status Description
2600 BadRequest 400 Invalid trigger request
2601 ResourceNotFound 404 Trigger resource not found
2602 InternalServerError 500 Trigger service error

OrgStripeMapping Errors (2700-2799)

Code Name Status Description
2700 StripeCustomerNotFound 404 Stripe customer not found
2701 OrgStripeMappingNotFound 404 Organization Stripe mapping not found
2702 OrgStripeMappingForOrgNotFound 404 Organization Stripe mapping for org not found
2703 InternalServerError 500 Organization Stripe mapping service error

ExternalProxy Errors (2800-2899)

Code Name Status Description
2801 InternalServerError 500 External proxy service error

Axios Errors (3000-3099)

Code Name Status Description
3000 BadRequest 400 Axios bad request
3001 Unauthorized 401 Axios unauthorized
3002 Forbidden 403 Axios forbidden
3003 NotFound 404 Axios resource not found
3004 InternalServerError 500 Axios service error

TriggerRefresh Errors (3100-3199)

Code Name Status Description
3100 BadRequest 400 Invalid trigger refresh request
3101 InternalServerError 500 Trigger refresh service error
3102 ResourceNotFound 404 Trigger refresh resource not found
3103 Gone 410 Trigger refresh resource gone
3104 RefreshNotPossible 422 Trigger refresh not possible
3105 ThermosError 500 Thermos error in trigger refresh

OrgMember Errors (3200-3299)

Code Name Status Description
3200 OrgMemberNotFound 404 Organization member not found
3201 InternalServerError 500 Organization member service error
3202 Forbidden 403 Organization member access forbidden
3203 BadRequest 400 Invalid organization member request
3204 UserOrgMappingNotFound 404 User organization mapping not found

OrgApiKey Errors (3300-3399)

Code Name Status Description
3300 InternalServerError 500 Organization API key service error
3301 ResourceNotFound 404 Organization API key not found
3302 BadRequest 400 Invalid organization API key request
3303 Forbidden 403 Organization API key access forbidden

UserOrgMapping Errors (3400-3499)

Code Name Status Description
3400 InternalServerError 500 User organization mapping service error
3401 Forbidden 403 User organization mapping access forbidden
3402 ResourceNotFound 404 User organization mapping not found
3403 BadRequest 400 Invalid user organization mapping request
3404 AlreadyExists 409 User organization mapping already exists

OrgInviteCode Errors (3500-3599)

Code Name Status Description
3500 InternalServerError 500 Organization invite code service error
3501 ResourceNotFound 404 Organization invite code not found
3502 BadRequest 400 Invalid organization invite code request
3503 Forbidden 403 Organization invite code access forbidden

MagicLink Errors (3600-3699)

Code Name Status Description
3600 InternalServerError 500 Magic link service error
3601 ResourceNotFound 404 Magic link not found
3602 BadRequest 400 Invalid magic link request
3603 Forbidden 403 Magic link access forbidden

ComposioTools Errors (3700-3799)

Code Name Status Description
3700 InvalidRequest 400 Invalid Composio tools request
3701 ExecutionError 500 Composio tools execution error
3702 ValidationError 400 Composio tools validation error
3703 ToolNotFound 404 Composio tools tool not found
3704 ConnectionError 500 Composio tools connection error
3705 SearchError 500 Composio tools search error
3706 InternalServerError 500 Composio tools service error

DebugLogs Errors (3800-3899)

Code Name Status Description
3800 BadRequest 400 Invalid debug logs request
3801 InternalServerError 500 Debug logs service error

Notification Errors (3850-3899)

Code Name Status Description
3850 BadRequest 400 Invalid notification request
3851 InternalServerError 500 Notification service error

ProjectFiles Errors (3900-3999)

Code Name Status Description
3900 BadRequest 400 Invalid project files request
3901 ResourceNotFound 404 Project file not found
3902 InternalServerError 500 Project files service error
3903 InvalidFileType 400 Invalid file type
3904 InvalidFileSize 400 Invalid file size
3905 InvalidDimensions 400 Invalid file dimensions
3906 UploadFailed 500 File upload failed
3907 StorageError 500 File storage error

Recipe Errors (4000-4099)

Code Name Status Description
4000 BadRequest 400 Invalid recipe request
4001 Unauthorized 401 Recipe access unauthorized
4002 ResourceNotFound 404 Recipe not found
4003 InternalServerError 500 Recipe service error

Sandbox Errors (4100-4199)

Code Name Status Description
4100 BadRequest 400 Invalid sandbox request
4101 Unauthorized 401 Sandbox access unauthorized
4102 ResourceNotFound 404 Sandbox resource not found
4103 InternalServerError 500 Sandbox service error

Thermos Service Error Codes

The Thermos service (Go) uses a different error code system:

Database Errors

Code Name HTTP Status Description
1 DbBadRequestError 400 Database bad request
2 DbNotFoundError 404 Database record not found
3 DbReadError 500 Database read error
4 DbWriteError 500 Database write error
5 DbDeleteError 500 Database delete error
6 DbInternalError 500 Database internal error

Error Types

Type Description
json_decode JSON decoding error
action_not_found Action not found
app_spec_not_found App specification not found
action_spec_not_found Action specification not found
lambda_invocation Lambda function invocation error
parse_map_to_struct Map to struct parsing error
json_encode JSON encoding error
proto_conversion Protocol buffer conversion error
trigger_not_found Trigger not found
trigger_spec_not_found Trigger specification not found

Error Handling Best Practices

  1. Always check the HTTP status code first to understand the general error category
  2. Use the specific error code for detailed error handling logic
  3. Check the suggested_fix field for user-friendly resolution guidance
  4. Include the request_id when reporting bugs or seeking support
  5. Handle validation errors by checking the errors array for specific field issues

Support and Reporting

When encountering errors:

  1. Include the full error response in bug reports
  2. Provide the request_id for faster debugging
  3. Check the suggested_fix field for immediate resolution steps
  4. Report persistent issues at Composio Support

Rate Limiting

  • 429 Too Many Requests: Rate limit exceeded
  • Check response headers for rate limit information
  • Implement exponential backoff for retry logic
  • Consider upgrading your plan for higher rate limits

Authentication Errors

Common authentication issues:

  • 401 Unauthorized: Invalid or missing API key
  • 403 Forbidden: Insufficient permissions
  • 401 NoAuthProvided: No authentication provided
  • 401 InvalidProjectAccess: API key doesn't have access to the project

Validation Errors

When receiving validation errors:

  1. Check the errors array for specific field validation failures
  2. Ensure all required fields are provided
  3. Verify field formats match the API specification
  4. Check for required headers and content types