Error Codes

Comprehensive list of API error codes and their meanings

​

Error Codes

The Inbound API returns standard HTTP status codes to indicate success or failure. Error responses include a JSON object with an error field describing the issue.

​

HTTP Status Codes

Status Code	Meaning	Description
200	Success	Request completed successfully
400	Bad Request	Invalid request parameters or missing required fields
401	Unauthorized	Invalid or missing API key
403	Forbidden	The API key or account is not allowed to do this (for example, sending is paused)
404	Not Found	Requested resource does not exist
422	Unprocessable Entity	The email provider rejected the message; retrying the same message will not succeed
429	Too Many Requests	Rate limit exceeded (100 requests/second per account across E2 endpoints)
500	Internal Server Error	Server error occurred

​

Common Error Types

​

Authentication Errors (401)

• Unauthorized - Missing or invalid API key
• Invalid API key - API key format is incorrect or expired

​

Validation Errors (400)

​

Missing Required Fields

• Missing required fields: from and to are required - Email sending
• Missing required fields: apiKey and to are required - Demo requests
• Missing required fields - General validation failure

​

Invalid Formats

• Invalid email format - Email address doesn’t match expected pattern
• Invalid email format: [email] - Specific email address validation
• Invalid webhook URL format - Webhook URL validation failure
• Invalid scheduled_at - Date/time format is incorrect
• Invalid schedule time - Scheduled time is in the past or too far in future

​

Configuration Errors

• Invalid endpoint type - Unsupported endpoint type specified
• Invalid configuration - Endpoint configuration validation failed
• Webhook URL is required - Missing webhook URL for webhook endpoints
• Forward-to email address is required - Missing email for forwarding endpoints
• Invalid forward-to email address format - Invalid forwarding email format

​

Parameter Errors

• Invalid limit parameter - List limit must be 1-100
• Invalid offset parameter - Offset must be non-negative
• Invalid email ID provided - Email ID format is incorrect
• Invalid webhook format - Unsupported webhook payload format

​

Sending Errors (403, 422)

• Sending is paused for this account. Please contact support. (403) - Sending is paused or suspended for your account; retrying will not help until it is resumed
• Email rejected by the email provider: [reason] (422) - The provider refused this message (for example, an invalid header or content it does not accept). Fix the message before sending it again
• Email rejected by the email provider as invalid: [reason] (422) - The provider considered the request invalid
• The custom MAIL FROM domain for this sender is not verified (422) - Verify the sending domain’s MAIL FROM records

​

Resource Errors (404)

• Email not found - Email doesn’t exist or user lacks access
• Endpoint not found - Endpoint doesn’t exist or access denied
• Scheduled email not found - Scheduled email not found or unauthorized
• Original email not found - Cannot reply to non-existent email

​

Rate Limiting (429)

• Too Many Requests - Too many requests (limit: 100 per second per account across E2 endpoints)
• Rate limit exceeded. Maximum 100 requests per second. Retry after 1 seconds. - Example rate limit message; the retry delay varies
• Sending rate limit reached. Please try again later. - The email provider is throttling sends; retry with backoff
• Email sending limit reached. Please upgrade your plan to send more emails. - Your plan’s sending limit is used up

​

Server Errors (500)

• Failed to send email. Please try again later. - A temporary failure while sending; retry with backoff. Rejections of the message itself return 422 instead (see Sending Errors)
• Failed to schedule email - Email scheduling failed
• Failed to cancel scheduled email - Cancellation operation failed
• Failed to test endpoint - Endpoint testing failed

​

Error Response Format

All error responses follow this structure:

{
  "error": "Error description",
  "message": "Additional context (optional)",
  "details": "Technical details (optional)"
}

​

Rate Limit Headers

When approaching or exceeding rate limits, responses include headers:

Header	Description
ratelimit-limit	Maximum requests per window
ratelimit-remaining	Requests remaining in current window
ratelimit-reset	Seconds until limit resets
retry-after	Seconds to wait before retry (429 only)