Email API Error Codes & Troubleshooting Guide
Common HTTP status codes and error responses returned by the Email API with reasons and fixes.
Authentication Errors
401 - AUTH_ERROR
Authentication failed
Reason: Invalid API key, signature mismatch, expired timestamp, or nonce reuse
Fix: Regenerate signature with correct payload and ensure fresh timestamp + unique nonce
Authentication failed
Reason: Invalid API key, signature mismatch, expired timestamp, or nonce reuse
Fix: Regenerate signature with correct payload and ensure fresh timestamp + unique nonce
Validation Errors
400 - INVALID_INPUT
Invalid request body
Cases:
• Missing required fields (projectId, apiKey, nonce, timestamp)
• Missing emailData
• Invalid email format (to / replyTo)
• Invalid templateName or templateData structure
• Invalid button URL or color format
Fix: Validate payload against schema before sending
Invalid request body
Cases:
• Missing required fields (projectId, apiKey, nonce, timestamp)
• Missing emailData
• Invalid email format (to / replyTo)
• Invalid templateName or templateData structure
• Invalid button URL or color format
Fix: Validate payload against schema before sending
Rate Limiting
429 - RATE_LIMIT_EXCEEDED
Too many requests
Reason: Requests per minute (RPM) exceeded
Fix: Retry later or upgrade plan
Too many requests
Reason: Requests per minute (RPM) exceeded
Fix: Retry later or upgrade plan
Server Errors
503 - SERVICE_UNAVAILABLE
Service under maintenance
Fix: Retry after some time
Service under maintenance
Fix: Retry after some time
500 - SERVER_ERROR
Unexpected failure during email processing
Fix: Retry or contact support if persistent
Unexpected failure during email processing
Fix: Retry or contact support if persistent
Ensure correct emailData schema, valid emails, and proper signature generation to avoid most errors.