Composio Error Codes Documentation

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