Error Codes

Complete reference of 33 error codes across 8 categories returned by the CPaaS Orchestrator Service.

Error response formatjson

{
  "error": {
    "code": "ERR_CPAAS_RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded for channel WHATSAPP",
    "http": 429
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Bad RequestHTTP 400

Code	HTTP	Description	Resolution
`ERR_CPAAS_INVALID_PHONE_NUMBER`	400	Phone number format is invalid (expected E.164)	Use E.164 format: +1234567890
`ERR_CPAAS_INVALID_EMAIL`	400	Email address format is invalid	Provide a valid email address
`ERR_CPAAS_INVALID_CHANNEL`	400	Unsupported messaging channel	Use: WHATSAPP, SMS, EMAIL, VOICE, or PUSH
`ERR_CPAAS_EMPTY_MESSAGE_BODY`	400	Message body cannot be empty	Provide a non-empty message_body
`ERR_CPAAS_TEMPLATE_NOT_FOUND`	400	Referenced template does not exist	Verify template_id or template name
`ERR_CPAAS_TEMPLATE_VARIABLES_MISSING`	400	Required template variables not provided	Include all required template variables
`ERR_CPAAS_INVALID_WEBHOOK_URL`	400	Webhook URL is not a valid HTTPS URL	Provide a valid HTTPS URL
`ERR_CPAAS_INVALID_PROVIDER_CONFIG`	400	Provider configuration is invalid	Check required config fields for the provider
`ERR_CPAAS_BULK_LIMIT_EXCEEDED`	400	Bulk message count exceeds max (1000)	Split into batches of 1000 or fewer
`ERR_CPAAS_VALIDATION_FAILED`	400	Request body validation failed	Check request body against API docs

UnauthorizedHTTP 401

Code	HTTP	Description	Resolution
`ERR_CPAAS_UNAUTHORIZED`	401	Missing or invalid authentication	Provide a valid Bearer JWT token
`ERR_CPAAS_TOKEN_EXPIRED`	401	JWT token has expired	Refresh the token via auth-svc /refresh endpoint
`ERR_CPAAS_INVALID_API_KEY`	401	Internal API key is invalid	Use the correct x-internal-api-key header

ForbiddenHTTP 403

Code	HTTP	Description	Resolution
`ERR_CPAAS_FORBIDDEN`	403	Insufficient permissions for this action	Request the required role from admin
`ERR_CPAAS_TIER_INSUFFICIENT`	403	Subscription tier too low for this feature	Upgrade subscription tier
`ERR_CPAAS_CHANNEL_DISABLED`	403	Channel not enabled for this tenant	Enable the channel in tenant settings

Not FoundHTTP 404

Code	HTTP	Description	Resolution
`ERR_CPAAS_MESSAGE_NOT_FOUND`	404	Delivery log not found for given ID	Verify the message ID exists
`ERR_CPAAS_PROVIDER_NOT_FOUND`	404	Provider configuration not found	Verify the provider ID exists for this tenant
`ERR_CPAAS_WEBHOOK_NOT_FOUND`	404	Webhook configuration not found	Verify the webhook ID exists
`ERR_CPAAS_PREFERENCE_NOT_FOUND`	404	User preference not found for email	Create preference first via PUT /preferences

ConflictHTTP 409

Code	HTTP	Description	Resolution
`ERR_CPAAS_DUPLICATE_IDEMPOTENCY_KEY`	409	Request with this Idempotency-Key already processed	Use a new Idempotency-Key or retrieve the existing result
`ERR_CPAAS_PROVIDER_ALREADY_EXISTS`	409	A provider with this name/type already exists	Update the existing provider instead
`ERR_CPAAS_TEMPLATE_NAME_TAKEN`	409	A template with this name already exists	Use a different template name

UnprocessableHTTP 422

Code	HTTP	Description	Resolution
`ERR_CPAAS_OPT_OUT_BLOCKED`	422	Recipient has opted out of this channel	Respect the opt-out or use a different channel
`ERR_CPAAS_TEMPLATE_NOT_APPROVED`	422	Template must be approved before use	Approve the template first via POST /templates/:id/approve

Rate LimitHTTP 429

Code	HTTP	Description	Resolution
`ERR_CPAAS_RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded for this channel	Wait for the rate limit window to reset
`ERR_CPAAS_QUOTA_EXCEEDED`	429	Monthly/daily quota exhausted	Upgrade subscription tier or wait for quota reset
`ERR_CPAAS_EMERGENCY_LIMIT`	429	Daily emergency broadcast limit reached (5/day)	Wait until tomorrow or contact support

Server / ProviderHTTP 500-503

Code	HTTP	Description	Resolution
`ERR_CPAAS_PROVIDER_UNAVAILABLE`	503	No healthy provider available for this channel	Retry; providers may be recovering
`ERR_CPAAS_PROVIDER_SEND_FAILED`	502	Provider returned an error when sending	Check provider status; message will be auto-retried
`ERR_CPAAS_INTERNAL_ERROR`	500	Unexpected internal server error	Retry; if persistent, contact support with request_id
`ERR_CPAAS_BOOTSTRAP_FAILED`	503	Service is still initializing	Retry in a few seconds (Lambda cold start)
`ERR_CPAAS_DATABASE_ERROR`	500	Database operation failed	Retry; Aurora Serverless may be scaling up