Get started

Errors and status codes

How EmailMarketer.io API errors look, which HTTP status codes the API uses, and the error codes every command can return.

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, 503 and network timeouts, with exponential backoff and jitter.
  • Do not retry 400, 401, 403, 404, 409 or 422 without 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.