Errors

Match the HTTP status and error code to the action your integration should take.

Email and activity errors

Email, outbound-message and suppression endpoints use Postmark’s shape:

Error response · HTTP 422

{
  "ErrorCode": 300,
  "Message": "Provide a TextBody, an HtmlBody, or both."
}

ErrorCode is separate from the HTTP status. For example, ErrorCode 401 means the From domain is not hosted and comes with HTTP 422; it is not an authentication error.

ErrorCode	HTTP	Meaning and action
`10`	401 / 403	Missing or invalid API key (401), or a key without the required scope (403). Check the key, its organization, revocation state, and endpoint scope.
`300`	422	Invalid message, field, header, pagination or date filter. Also returned for an unknown email or activity endpoint. Read Message for the exact field. Correct the request before retrying.
`400`	422	The From domain is not verified on this organization. Ask an organization admin to verify the domain or use a verified From domain.
`401`	422	The From domain is verified but not hosted on the Prawnwire mail server. Finish hosting setup so outgoing mail can be DKIM-signed.
`402`	422	The request body is not valid JSON. Serialize the body as JSON. Check escaping and trailing commas.
`405`	422	The monthly allowance or daily cap cannot fit the non-suppressed recipients in this message. Read the usage and reset information. Wait for the reset or ask an admin to request more.
`406`	422	Every recipient is suppressed. Nothing was queued. Inspect suppressions and resolve their cause before reactivating an address.
`409`	422	The request does not declare a JSON body. Set Content-Type: application/json.
`410`	422	The batch contains more than 500 messages. Split the array into batches of at most 500.
`411`	422	An attachment has a forbidden filename extension. Remove the executable or script attachment. See Attachments for the full list.
`412`	422	The organization is suspended. Ask an organization admin to resolve the suspension.
`429`	429	This API key has exceeded its request rate limit. Wait for Retry-After, currently 60 seconds, before retrying.
`701`	422	The message was not found in this organization. Check the MessageID. Test sends do not exist in activity, and messages expire after 30 days.
`1235`	422	The message stream is not supported. Use outbound in the path and MessageStream field.

ErrorCode: 0 is success, not an error. A test send also returns 0, but does not queue mail. In a valid batch envelope, per-message errors appear inside an HTTP 200 array. Inspect every entry.

Account endpoint errors

/v1/me, /v1/domains, and /v1/members use this shape:

Account error · HTTP 403

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key needs the domains:read scope."
  }
}

Code	HTTP	What to do
`unauthorized`	401	Supply an active key in an accepted header.
`insufficient_scope`	403	Ask an admin for a key with the endpoint’s scope.
`org_suspended`	403	Ask an admin to resolve the organization’s suspension.
`rate_limited`	429	Wait for `Retry-After` before trying again.
`not_found`	404	Check the account endpoint path.

Transport failures

An oversized HTTP body can be rejected before these handlers, with HTTP 413. Proxy errors and infrastructure failures may not have either JSON error shape. Check Content-Type and HTTP status before assuming the response body matches a send result.

On a network timeout after submission, the message might already be queued. There is no documented idempotency key. Check activity before retrying, and never replay successful batch entries. See Rate limits for safe retry handling.

Errors.

Email and activity errors

Account endpoint errors

Transport failures