Error Codes

Complete reference of 76 error codes across 14 categories returned by the Cypher Service.

Error response formatjson

{
  "error": {
    "code": "ERR_CYPHER_SVC_CONVERSATION_NOT_FOUND",
    "message": "Conversation not found",
    "statusCode": 404
  }
}

Conversation1000-1099

Code	HTTP	Name	Description	Resolution
`ERR_CYPHER_SVC_CONVERSATION_NOT_FOUND`	404	`CONVERSATION_NOT_FOUND`	Conversation not found	Verify the threadId exists
`ERR_CYPHER_SVC_CONVERSATION_ALREADY_EXISTS`	409	`CONVERSATION_ALREADY_EXISTS`	Conversation already exists with this thread ID	Use a different threadId or resume the existing conversation
`ERR_CYPHER_SVC_CONVERSATION_INVALID_STATE`	422	`CONVERSATION_INVALID_STATE`	Conversation is in an invalid state	Check conversation status before performing the action
`ERR_CYPHER_SVC_CONVERSATION_STATE_TRANSITION_INVALID`	422	`STATE_TRANSITION_INVALID`	Invalid state transition attempted	Follow the valid state machine: active -> completed/archived
`ERR_CYPHER_SVC_CONVERSATION_MAX_MESSAGES_EXCEEDED`	422	`MAX_MESSAGES_EXCEEDED`	Maximum messages per conversation exceeded	Start a new conversation or upgrade subscription tier
`ERR_CYPHER_SVC_CONVERSATION_ARCHIVED`	410	`CONVERSATION_ARCHIVED`	Conversation has been archived	Start a new conversation
`ERR_CYPHER_SVC_CONVERSATION_EXPIRED`	410	`CONVERSATION_EXPIRED`	Conversation has expired	Start a new conversation

Session1100-1199

Code	HTTP	Name	Description	Resolution
`ERR_CYPHER_SVC_SESSION_NOT_FOUND`	404	`SESSION_NOT_FOUND`	Session not found	Create a new session via /command
`ERR_CYPHER_SVC_SESSION_EXPIRED`	401	`SESSION_EXPIRED`	Session has expired	Create a new session
`ERR_CYPHER_SVC_SESSION_INVALID`	401	`SESSION_INVALID`	Invalid session	Verify session ID and re-authenticate
`ERR_CYPHER_SVC_SESSION_MAX_CONCURRENT_EXCEEDED`	429	`MAX_CONCURRENT_EXCEEDED`	Maximum concurrent sessions exceeded	Close existing sessions or upgrade tier

Task1200-1299

Code	HTTP	Name	Description	Resolution
`ERR_CYPHER_SVC_TASK_NOT_FOUND`	404	`TASK_NOT_FOUND`	Task not found	Verify the taskId exists
`ERR_CYPHER_SVC_TASK_ALREADY_EXISTS`	409	`TASK_ALREADY_EXISTS`	Task already exists	Use a different idempotency key
`ERR_CYPHER_SVC_TASK_EXECUTION_FAILED`	500	`TASK_EXECUTION_FAILED`	Task execution failed	Retry; check task logs for details
`ERR_CYPHER_SVC_TASK_INVALID_STATUS`	422	`TASK_INVALID_STATUS`	Invalid task status	Verify task is in a valid state for the operation
`ERR_CYPHER_SVC_TASK_MAX_RETRIES_EXCEEDED`	500	`MAX_RETRIES_EXCEEDED`	Maximum task retries exceeded	Create a new task; investigate root cause
`ERR_CYPHER_SVC_TASK_TIMEOUT`	504	`TASK_TIMEOUT`	Task execution timeout	Reduce task complexity or retry

Nudge1300-1399

Code	HTTP	Name	Description	Resolution
`ERR_CYPHER_SVC_NUDGE_NOT_FOUND`	404	`NUDGE_NOT_FOUND`	Nudge not found	Verify the nudgeId exists
`ERR_CYPHER_SVC_NUDGE_ALREADY_SENT`	409	`NUDGE_ALREADY_SENT`	Nudge has already been sent	Schedule a new nudge instead
`ERR_CYPHER_SVC_NUDGE_SCHEDULING_FAILED`	500	`SCHEDULING_FAILED`	Failed to schedule nudge	Retry; check notification service availability
`ERR_CYPHER_SVC_NUDGE_MAX_SCHEDULED_EXCEEDED`	422	`MAX_SCHEDULED_EXCEEDED`	Maximum scheduled nudges exceeded	Cancel existing nudges or upgrade tier

Intent & NLU1400-1499

Code	HTTP	Name	Description	Resolution
`ERR_CYPHER_SVC_INTENT_DETECTION_FAILED`	500	`INTENT_DETECTION_FAILED`	Failed to detect user intent	Retry; AI service may be temporarily unavailable
`ERR_CYPHER_SVC_INTENT_UNKNOWN`	422	`INTENT_UNKNOWN`	Could not determine user intent	Rephrase the message with clearer intent
`ERR_CYPHER_SVC_INTENT_CONFIDENCE_TOO_LOW`	422	`CONFIDENCE_TOO_LOW`	Intent confidence is too low	Provide more context in the message
`ERR_CYPHER_SVC_ENTITY_EXTRACTION_FAILED`	500	`ENTITY_EXTRACTION_FAILED`	Failed to extract entities	Retry; NLU service may be overloaded
`ERR_CYPHER_SVC_ENTITY_VALIDATION_FAILED`	422	`ENTITY_VALIDATION_FAILED`	Entity validation failed	Check extracted entity values and formats
`ERR_CYPHER_SVC_ENTITY_MISSING_REQUIRED`	422	`ENTITY_MISSING_REQUIRED`	Required entities are missing	Include all required entities in the message

AI Credits1500-1599

Code	HTTP	Name	Description	Resolution
`ERR_CYPHER_SVC_INSUFFICIENT_CREDITS`	402	`INSUFFICIENT_CREDITS`	Insufficient AI credits	Purchase credits or upgrade subscription tier
`ERR_CYPHER_SVC_CREDIT_RESERVATION_FAILED`	500	`CREDIT_RESERVATION_FAILED`	Failed to reserve credits	Retry; wallet service may be unavailable
`ERR_CYPHER_SVC_CREDIT_DEDUCTION_FAILED`	500	`CREDIT_DEDUCTION_FAILED`	Failed to deduct credits	Credits were reserved but deduction failed; contact support
`ERR_CYPHER_SVC_CREDIT_CALCULATION_ERROR`	500	`CREDIT_CALCULATION_ERROR`	Error calculating credit cost	Retry; internal pricing error

Rate Limiting1600-1699

Code	HTTP	Name	Description	Resolution
`ERR_CYPHER_SVC_RATE_LIMIT_EXCEEDED`	429	`RATE_LIMIT_EXCEEDED`	Rate limit exceeded	Implement exponential backoff; check Retry-After header
`ERR_CYPHER_SVC_QUOTA_EXCEEDED`	429	`QUOTA_EXCEEDED`	Quota exceeded	Wait for quota reset or upgrade tier
`ERR_CYPHER_SVC_CONCURRENT_LIMIT_EXCEEDED`	429	`CONCURRENT_LIMIT_EXCEEDED`	Concurrent request limit exceeded	Reduce parallel requests

Tier & Subscription1700-1799

Code	HTTP	Name	Description	Resolution
`ERR_CYPHER_SVC_TIER_FEATURE_NOT_AVAILABLE`	403	`TIER_FEATURE_NOT_AVAILABLE`	Feature not available in your subscription tier	Upgrade to access this feature
`ERR_CYPHER_SVC_TIER_LIMIT_EXCEEDED`	429	`TIER_LIMIT_EXCEEDED`	Subscription tier limit exceeded	Upgrade tier for higher limits
`ERR_CYPHER_SVC_TIER_INVALID`	422	`TIER_INVALID`	Invalid subscription tier	Verify subscription status
`ERR_CYPHER_SVC_UPGRADE_REQUIRED`	402	`UPGRADE_REQUIRED`	Subscription upgrade required	Upgrade to Pro or Enterprise tier

WhatsApp1800-1899

Code	HTTP	Name	Description	Resolution
`ERR_CYPHER_SVC_WHATSAPP_WEBHOOK_VERIFICATION_FAILED`	401	`WEBHOOK_VERIFICATION_FAILED`	WhatsApp webhook verification failed	Check verify token configuration
`ERR_CYPHER_SVC_WHATSAPP_MESSAGE_SEND_FAILED`	500	`MESSAGE_SEND_FAILED`	Failed to send WhatsApp message	Retry; check Meta API status
`ERR_CYPHER_SVC_WHATSAPP_INVALID_SIGNATURE`	401	`INVALID_SIGNATURE`	Invalid WhatsApp webhook signature	Verify app secret is correct
`ERR_CYPHER_SVC_WHATSAPP_INVALID_PAYLOAD`	400	`INVALID_PAYLOAD`	Invalid WhatsApp webhook payload	Check payload format against Meta docs
`ERR_CYPHER_SVC_WHATSAPP_PHONE_NOT_REGISTERED`	404	`PHONE_NOT_REGISTERED`	Phone number not registered for WhatsApp	Verify phone number is registered with WhatsApp

AI Service Integration1900-1999

Code	HTTP	Name	Description	Resolution
`ERR_CYPHER_SVC_AIBRAIN_SERVICE_UNAVAILABLE`	503	`AIBRAIN_SERVICE_UNAVAILABLE`	AIBrain service is unavailable	Retry; ECS Fargate service may be scaling
`ERR_CYPHER_SVC_AIBRAIN_REQUEST_FAILED`	500	`AIBRAIN_REQUEST_FAILED`	AIBrain request failed	Check aibrain-svc logs for details
`ERR_CYPHER_SVC_LLM_ORCH_SERVICE_UNAVAILABLE`	503	`LLM_ORCH_SERVICE_UNAVAILABLE`	LLM Orchestrator service is unavailable	Retry; llm-orch-svc may be scaling
`ERR_CYPHER_SVC_RAG_SERVICE_UNAVAILABLE`	503	`RAG_SERVICE_UNAVAILABLE`	RAG service is unavailable	Retry; rag-svc may be scaling
`ERR_CYPHER_SVC_MCP_SERVICE_UNAVAILABLE`	503	`MCP_SERVICE_UNAVAILABLE`	MCP service is unavailable	Retry; mcp-svc may be scaling
`ERR_CYPHER_SVC_TTS_SERVICE_UNAVAILABLE`	503	`TTS_SERVICE_UNAVAILABLE`	Text-to-speech service is unavailable	Retry or use text-only response
`ERR_CYPHER_SVC_STT_SERVICE_UNAVAILABLE`	503	`STT_SERVICE_UNAVAILABLE`	Speech-to-text service is unavailable	Retry or send text input instead
`ERR_CYPHER_SVC_VIDEO_PERSONA_SERVICE_UNAVAILABLE`	503	`VIDEO_PERSONA_UNAVAILABLE`	Video persona service is unavailable	Retry or fall back to text/audio

Inter-Service2000-2099

Code	HTTP	Name	Description	Resolution
`ERR_CYPHER_SVC_WALLET_SERVICE_UNAVAILABLE`	503	`WALLET_SERVICE_UNAVAILABLE`	Wallet service is unavailable	Retry; wallet-svc may be scaling
`ERR_CYPHER_SVC_EVENT_SERVICE_UNAVAILABLE`	503	`EVENT_SERVICE_UNAVAILABLE`	Event service is unavailable	Retry; event-svc Lambda may be cold starting
`ERR_CYPHER_SVC_USER_SERVICE_UNAVAILABLE`	503	`USER_SERVICE_UNAVAILABLE`	User service is unavailable	Retry; user-svc Lambda may be cold starting
`ERR_CYPHER_SVC_NOTIFY_SERVICE_UNAVAILABLE`	503	`NOTIFY_SERVICE_UNAVAILABLE`	Notification service is unavailable	Retry; notify-svc Lambda may be cold starting
`ERR_CYPHER_SVC_INTEGRATION_HUB_UNAVAILABLE`	503	`INTEGRATION_HUB_UNAVAILABLE`	Integration Hub service is unavailable	Retry; integration-hub-svc Lambda may be cold starting

Validation2100-2199

Code	HTTP	Name	Description	Resolution
`ERR_CYPHER_SVC_VALIDATION_FAILED`	400	`VALIDATION_FAILED`	Validation failed	Check request body against API docs
`ERR_CYPHER_SVC_INVALID_INPUT`	400	`INVALID_INPUT`	Invalid input provided	Review field constraints
`ERR_CYPHER_SVC_INVALID_PHONE_NUMBER`	400	`INVALID_PHONE_NUMBER`	Invalid phone number format	Use E.164 format (e.g., +1234567890)
`ERR_CYPHER_SVC_INVALID_MESSAGE_FORMAT`	400	`INVALID_MESSAGE_FORMAT`	Invalid message format	Check supported message types
`ERR_CYPHER_SVC_INVALID_CHANNEL`	400	`INVALID_CHANNEL`	Invalid communication channel	Use: WEB, MOBILE, WHATSAPP, SMS, VOICE, API
`ERR_CYPHER_SVC_MESSAGE_TOO_LONG`	400	`MESSAGE_TOO_LONG`	Message exceeds maximum length	Shorten message to under 4096 characters

Infrastructure2200-2599

Code	HTTP	Name	Description	Resolution
`ERR_CYPHER_SVC_IDEMPOTENCY_KEY_CONFLICT`	409	`IDEMPOTENCY_KEY_CONFLICT`	Idempotency key conflict	Use a different idempotency key
`ERR_CYPHER_SVC_DUPLICATE_REQUEST`	409	`DUPLICATE_REQUEST`	Duplicate request detected	Request already processed; check previous response
`ERR_CYPHER_SVC_CACHE_ERROR`	500	`CACHE_ERROR`	Cache operation error	Retry; Redis may be temporarily unavailable
`ERR_CYPHER_SVC_DATABASE_ERROR`	500	`DATABASE_ERROR`	Database error occurred	Retry; Aurora Serverless may be scaling
`ERR_CYPHER_SVC_DATABASE_CONNECTION_FAILED`	503	`DATABASE_CONNECTION_FAILED`	Database connection failed	Retry after a few seconds
`ERR_CYPHER_SVC_KAFKA_PUBLISH_FAILED`	500	`KAFKA_PUBLISH_FAILED`	Failed to publish Kafka event	Event may be retried via outbox pattern

General9000-9099

Code	HTTP	Name	Description	Resolution
`ERR_CYPHER_SVC_INTERNAL_SERVER_ERROR`	500	`INTERNAL_SERVER_ERROR`	Internal server error	Retry; if persistent, contact support with request_id
`ERR_CYPHER_SVC_SERVICE_UNAVAILABLE`	503	`SERVICE_UNAVAILABLE`	Service temporarily unavailable	Retry with exponential backoff
`ERR_CYPHER_SVC_TIMEOUT`	504	`TIMEOUT`	Request timeout	Reduce request complexity or retry
`ERR_CYPHER_SVC_UNAUTHORIZED`	401	`UNAUTHORIZED`	Unauthorized access	Provide a valid JWT token
`ERR_CYPHER_SVC_FORBIDDEN`	403	`FORBIDDEN`	Access forbidden	Check required roles/permissions
`ERR_CYPHER_SVC_NOT_FOUND`	404	`NOT_FOUND`	Resource not found	Verify the resource ID and path
`ERR_CYPHER_SVC_CONFLICT`	409	`CONFLICT`	Resource conflict	Resolve the conflict and retry
`ERR_CYPHER_SVC_UNPROCESSABLE_ENTITY`	422	`UNPROCESSABLE_ENTITY`	Unprocessable entity	Check request body format and values