Errors & Status Codes
The EmailSendX API uses standard HTTP status codes. Every error response includes a human-readable error field in the JSON body to help you diagnose issues quickly.
Error Response Format
All error responses have a consistent JSON structure:
{
"error": "Human-readable description of what went wrong"
}The error field always contains a message written for developers. It describes the problem clearly enough to act on without needing to look up error codes.
Successful responses do not include an error field. You can always check the HTTP status code first: 2xx means success, 4xx means a client error, 5xx means a server error.
HTTP Status Codes
| Code | Status | Meaning | Action |
|---|---|---|---|
| 200 | OK | The request succeeded and returned the requested data. | No action needed. |
| 201 | Created | A new resource was created successfully. | The response body contains the new resource. |
| 202 | Accepted | An async operation was accepted and will be processed. | The result will be available via webhook or polling. |
| 400 | Bad Request | The request body was invalid, malformed JSON, or a required field was missing. | Check the error message for the specific field or validation issue. |
| 401 | Unauthorized | The API key was missing, invalid, revoked, or the key's IP restriction blocked the request. | Verify your API key is correct and hasn't been deleted. |
| 403 | Forbidden | The API key is valid but lacks the required scope for this operation. | Add the required scope to your key in Settings → API. |
| 404 | Not Found | The requested resource doesn't exist or doesn't belong to this workspace. | Verify the resource ID and that it belongs to the workspace of your API key. |
| 429 | Too Many Requests | You've exceeded the rate limit of 120 requests/minute. | Check the Retry-After header and wait before retrying. |
| 500 | Internal Server Error | An unexpected error occurred on the server. | Retry with exponential backoff. If it persists, contact support. |
On 5xx errors, use exponential backoff
On 401, check your key status
Common Error Messages
Below are frequently encountered error messages, what causes them, and how to fix them.
| Error Message | Status | Cause & Fix |
|---|---|---|
| "Invalid email address" | 400 | The email field is not a valid email format. Check for typos or missing @ symbol. |
| "email is required" | 400 | The request body is missing the required email field. Include it in your JSON body. |
| "List not found in workspace" | 404 | The listId you provided does not belong to your workspace. Verify the list ID using GET /lists. |
| "Contact not found" | 404 | The contact ID in the URL path does not exist in this workspace. Confirm the contact ID is correct. |
| "Automation not found or not active" | 404 | The automation ID doesn't exist, belongs to another workspace, or is paused/draft. Only active automations can be enrolled via API. |
| "Missing required scope: contacts:write" | 403 | Your API key does not have the contacts:write scope. Edit the key in Settings → API to add the scope. |
| "API key not found or has been revoked" | 401 | The key in your Authorization header has been deleted. Create a new key and update your integration. |
| "Rate limit exceeded. Retry after N seconds." | 429 | You've sent more than 120 requests in the last minute. Wait the specified seconds before retrying. |
| "Request body too large" | 400 | The bulk contacts array or event data payload exceeds the size limit. Split bulk imports into smaller batches. |
| "contacts array must not exceed 1000 items" | 400 | You passed more than 1,000 contacts to the bulk endpoint. Split your import into batches of ≤1,000. |
Still stuck?
If you're seeing an error not listed here, reach out to support with your request details and the error message.