Error Codes

Complete reference of 42 error codes across 16 categories returned by the Notification Service.

Error response formatjson

{
  "error": {
    "code": "ERR_NOTIFY_INVALID_CHANNEL",
    "message": "Invalid notification channel. Must be one of: whatsapp, sms, email, push",
    "http": 400
  }
}

Quota Errors1

Code	HTTP	Description	Resolution
`ERR_NOTIFY_QUOTA_EXCEEDED`	402	Notification quota exceeded for your subscription tier	Upgrade subscription tier or wait for monthly quota reset

Validation Errors5

Code	HTTP	Description	Resolution
`ERR_NOTIFY_INVALID_CHANNEL`	400	Invalid notification channel	Use: whatsapp, sms, email, or push
`ERR_NOTIFY_INVALID_TEMPLATE`	400	Invalid template format or structure	Check Handlebars syntax and required fields
`ERR_NOTIFY_INVALID_CONTACT`	400	Invalid contact information	Verify email format, phone in E.164, or valid push token
`ERR_NOTIFY_MISSING_TEMPLATE_VARIABLES`	400	Missing required template variables	Provide all variables marked as required
`ERR_NOTIFY_TEMPLATE_RENDERING_FAILED`	400	Failed to render template	Check variable values match expected types

User Preference Errors3

Code	HTTP	Description	Resolution
`ERR_NOTIFY_QUIET_HOURS`	400	User has quiet hours enabled	Notification will be rescheduled. Use priority: "critical" to bypass
`ERR_NOTIFY_FREQUENCY_CAP_EXCEEDED`	400	Too many notifications recently	Wait for cap reset. Use category transactional or system to bypass
`ERR_NOTIFY_USER_OPTED_OUT`	400	User has opted out of this channel	Try a different channel or ask user to re-enable

Suppression Errors3

Code	HTTP	Description	Resolution
`ERR_NOTIFY_SUPPRESSED_CONTACT`	400	Contact is on suppression list	Check POST /suppressions/check before sending
`ERR_NOTIFY_BOUNCED_CONTACT`	400	Contact has bounced previously	Hard bounces are permanent. Verify contact info
`ERR_NOTIFY_COMPLAINED_CONTACT`	400	Contact has filed a spam complaint	Do not remove without explicit user consent

Idempotency Errors2

Code	HTTP	Description	Resolution
`ERR_NOTIFY_DUPLICATE_REQUEST`	409	Request already processed	Original response returned. Not an error
`ERR_NOTIFY_IDEMPOTENCY_KEY_MISMATCH`	409	Idempotency key mismatch	Use a unique key per unique request

Rate Limiting Errors1

Code	HTTP	Description	Resolution
`ERR_RATE_LIMIT_EXCEEDED`	429	API rate limit exceeded	Wait and retry with exponential backoff. Check Retry-After header

Delivery Errors3

Code	HTTP	Description	Resolution
`ERR_NOTIFY_DELIVERY_FAILED`	500	Notification delivery failed	Auto-retries up to max_retries. Check GET /deliveries/:id
`ERR_NOTIFY_PROVIDER_UNAVAILABLE`	500	CPaaS provider temporarily unavailable	System will attempt fallback channels
`ERR_NOTIFY_PROVIDER_ERROR`	500	CPaaS provider returned an error	Check error_code and error_message on delivery response

Integration Errors4

Code	HTTP	Description	Resolution
`ERR_INTEGRATION_HUB_UNAVAILABLE`	503	Integration Hub service unavailable	External provider gateway down. Retry shortly
`ERR_USER_SERVICE_UNAVAILABLE`	503	User service unavailable	Cannot resolve user contacts. Retry shortly
`ERR_VAULT_SERVICE_UNAVAILABLE`	503	Vault service unavailable	Cannot retrieve provider credentials. Retry shortly
`ERR_WALLET_SERVICE_UNAVAILABLE`	503	Wallet service unavailable	Cannot verify/deduct AI credits. Retry shortly

Template Errors3

Code	HTTP	Description	Resolution
`ERR_NOTIFY_TEMPLATE_NOT_FOUND`	404	Template not found	Verify template ID exists for current tenant
`ERR_NOTIFY_TEMPLATE_INACTIVE`	400	Template is inactive	Activate via POST /templates/:id/activate
`ERR_NOTIFY_TEMPLATE_DUPLICATE_NAME`	400	Template name already exists	Use a unique name per channel per tenant

Rule Errors3

Code	HTTP	Description	Resolution
`ERR_NOTIFY_RULE_NOT_FOUND`	404	Notification rule not found	Verify rule ID exists and is not soft-deleted
`ERR_NOTIFY_RULE_INVALID`	400	Invalid rule configuration	Check source_event, template_id, and JSONLogic filter
`ERR_NOTIFY_RULE_DUPLICATE`	400	Rule for this source event already exists	Use unique source_event + channel combo per tenant

Scheduling Errors4

Code	HTTP	Description	Resolution
`ERR_NOTIFY_SCHEDULE_NOT_FOUND`	404	Scheduled notification not found	Verify delivery ID exists in scheduled status
`ERR_NOTIFY_SCHEDULE_ALREADY_SENT`	400	Scheduled notification already sent	Cannot cancel or reschedule after dispatch
`ERR_NOTIFY_SCHEDULE_INVALID_TIME`	400	Scheduled time must be in the future	Provide timestamp at least 1 minute ahead
`ERR_NOTIFY_CANCEL_NOT_PENDING`	400	Only pending deliveries can be cancelled	Delivery must be in pending or scheduled status

Channel Errors3

Code	HTTP	Description	Resolution
`ERR_NOTIFY_CHANNEL_NOT_SUPPORTED`	400	Channel not supported	Use: email, sms, whatsapp, or push
`ERR_NOTIFY_CHANNEL_DISABLED`	400	Channel currently disabled	Contact admin to re-enable
`ERR_NOTIFY_CHANNEL_CONFIG_INVALID`	400	Invalid channel configuration	Check rate_limit, priority, and enabled fields

Notification CRUD Errors5

Code	HTTP	Description	Resolution
`ERR_NOTIFY_NOTIFICATION_NOT_FOUND`	404	Notification not found	Verify notification ID for current tenant
`ERR_NOTIFY_ALREADY_READ`	400	Notification already marked as read	Idempotent; no action needed
`ERR_NOTIFY_RETRY_NOT_ALLOWED`	400	Only failed deliveries can be retried	Check delivery status via GET /deliveries/:id
`ERR_NOTIFY_MAX_RETRIES_EXCEEDED`	400	Maximum retry attempts exceeded	Create a new notification instead
`ERR_NOTIFY_DELIVERY_NOT_FOUND`	404	Delivery record not found	Verify delivery ID for current tenant

Authorization Errors2

Code	HTTP	Description	Resolution
`ERR_NOTIFY_INSUFFICIENT_PERMISSIONS`	403	Insufficient permissions	Verify user has required role (user, organizer, admin)
`ERR_NOTIFY_TENANT_MISMATCH`	403	Tenant context mismatch	Ensure JWT token matches the target tenant

Send / Bulk Send Errors3

Code	HTTP	Description	Resolution
`ERR_NOTIFY_BULK_LIMIT_EXCEEDED`	400	Max 1000 notifications per bulk request	Split into batches of 1000 or fewer
`ERR_NOTIFY_BULK_PARTIAL_FAILURE`	207	Some bulk notifications failed	Check results array for individual status
`ERR_NOTIFY_MISSING_RECIPIENT`	400	Recipient user_id or contact info required	Provide user_id or direct contact (email, phone, push_token)

Analytics Errors2

Code	HTTP	Description	Resolution
`ERR_NOTIFY_ANALYTICS_INVALID_RANGE`	400	Invalid date range for analytics	Ensure from_date < to_date, both valid ISO 8601
`ERR_NOTIFY_ANALYTICS_EXPORT_FAILED`	500	Analytics export failed	Retry. Check CloudWatch logs if persistent