Errors - Mailercloud API

Each product returns a distinct error envelope. This page maps all of them.

Marketing API (`cloudapi.mailercloud.com`)

Standard HTTP status codes with a field-level error array:

{
  "errors": [
    { "field": "sender_email", "message": "sender_email must be a valid email address" }
  ]
}

HTTP	Meaning	Retry?
`400`	Validation failed — see `errors[].field`	No — fix the request
`401`	Missing/invalid API key	No
`404`	Resource not found	No
`429`	Rate limited — see Rate limits	Yes, with backoff
`5xx`	Server error	Yes, with backoff

Email API (`email-api.mailercloud.com`)

The Email API returns an envelope with its own internal status code system:

{ "status": "SUCCESS", "statusCode": 1000, "message": "NA" }

Always check statusCode, not just the HTTP status. Some delivery-outcome codes are returned with HTTP 200 even though they represent a failure (e.g. 9007 Hard bounce). An agent or client that keys only off HTTP status will misread these as success.

Internal status codes

Code	Meaning	Typical HTTP	Retry?
`1000`	Success	200	—
`9001`	Throttling error	429	✅ backoff
`9002`	Message sending quota exceeded	200	❌ raise quota
`9003`	Authentication failure	403	❌
`9004`	Recipient address not specified	400	❌
`9005`	From field missing	400	❌
`9006`	Soft bounce (temporarily deferred)	200	✅ later
`9007`	Hard bounce	200	❌ remove address
`9008`	Email reported as spam	200	❌
`9009`	Email unsubscribed	200	❌
`9010`	Email in suppression list	200	❌
`9011`	Sender address not verified	400	❌ verify sender
`9012`	ESP rejected message	200	❌
`9013`	Request to ESP expired	200	✅
`9014`	ESP unavailable	500	✅ backoff
`9015`	IP not whitelisted with ESP	401	❌
`9016`	Subject field empty	400	❌
`9017`	Invalid sender address	400	❌
`9018`	Invalid email address	400	❌
`9019`	Recipient’s mailbox is full	200	✅ later
`9021`	Mailbox not found on email server	200	❌
`9022`	Unsupported version	400	❌ — use `1.0`/`2.0`
`9024`	Authorization failure	403	❌
`9452`	Message overloading	200	✅ backoff
`9512`	Host email server not found	200	❌
`9999`	Unknown error occurred	200	✅ once, then investigate
`8000`	Campaign ID required for inbox tracking	400	❌
`8001`	Campaign ID format invalid (alphanumeric/hyphen/tilde, ≤100 chars)	400	❌

Email Verifier API (`verify.mailercloud.com`)

Simple error object with standard HTTP semantics:

{ "error": "Invalid or inactive API key" }

HTTP	Meaning	Retry?
`400`	Invalid request (bad JSON, >50 emails, missing file)	No
`401`	Missing/invalid API key	No
`402`	Insufficient credits	No — buy credits
`413`	File too large (>10 MB or >100k emails)	No
`503`	Service busy	Yes, with backoff