The API returns errors in one of two formats, depending on the command.
Error formats
Legacy format. Most commands on /api.php answer with HTTP 200 and a Success flag. ErrorCode is a number or an array of numbers:
{ "Success": false, "ErrorCode": [1], "ErrorText": "" }
Check Success first. Do not rely on the HTTP status for these commands.
Errors array. Newer commands and the transactional endpoints use HTTP status codes and an Errors array:
{ "Errors": [{ "Code": 8, "Message": "Missing Subject" }] }
Each reference page says which format a command uses and lists its own error codes. Codes are only meaningful together with the command that returned them. Code 4 from subscriber.create and code 4 from list.update mean different things.
HTTP status codes
| Status | Meaning |
|---|---|
| 200 | The request was handled. For legacy commands, check Success |
| 400 | Malformed request: invalid JSON, wrong method, unknown command, or an array sent where a single value is expected |
| 401 | Invalid sender API key (transactional endpoints) |
| 403 | The account, key or team role is not allowed to do this |
| 404 | The object does not exist or belongs to another account |
| 409 | Conflict: a suppressed recipient, a duplicate in flight, or a confirmation is needed |
| 410 | An export file has expired |
| 422 | Validation failed. Fix the request before you retry |
| 429 | Too many requests. Wait and retry |
| 500, 503 | Server error. Retry with backoff |
| 502 | The message could not be handed on. See the endpoint’s notes before you retry |
Codes every command can return
| Code | HTTP | Meaning |
|---|---|---|
99998 |
200 | Authentication failed: missing or invalid API key |
99999 |
200 | The account does not have permission for this command |
99997 |
200 | The object does not exist or belongs to another account (list reports) |
100000 |
400 | The JSON body could not be parsed |
100001 |
400 | HTTP method not allowed for this command |
100003 |
400 | Unknown command |
100017 |
400 | An array was sent for a parameter that takes one value |
100002, 100004, 100005 |
500 | Server error |
100021 |
403 | The team member’s role does not allow this command |
429 |
429 | Too many requests |
Agent keys used by AI assistants can also return codes 100010 to 100016. See AI assistants (MCP).
When to retry
- Retry
429,500,503and network timeouts, with exponential backoff and jitter. - Do not retry
400,401,403,404,409or422without changing the request. - For transactional sends, a retry can send the same email twice. Use an idempotency key when you retry.
Rate limits
The API limits how many requests an account can make in a short window. When you go over it, you get HTTP 429. Spread bursts through a queue. If your normal traffic hits the limit, contact us about your volume.