Errors

Every Send API error uses one envelope:

{
  "error": {
    "type": "validation_error",
    "code": "routing_provider_not_configured",
    "message": "Pinned provider(s) not configured on this project: postmark-api. Attach them or drop the routing pin."
  }
}

Branch on code — it’s stable. message is for humans and may change.

Codes

Status	type	code	Meaning
401	authentication_error	(varies)	Missing, malformed, or revoked API key — or a mw_live_… key used off api.mailway.net. See Authentication.
402	quota_error	monthly_quota_exceeded	The plan’s monthly message quota is spent. Free tier only — paid plans soft-overage.
402	quota_error	throughput_quota_exceeded	The plan’s monthly data-volume cap (including its grace margin on paid plans) is spent.
422	validation_error	(field errors)	The request body failed validation — the response lists the offending fields and caps.
422	validation_error	idempotency_key:invalid / idempotency_key:invalid_length	Malformed Idempotency-Key — 12–40 chars of [A-Za-z0-9_-].
422	validation_error	scheduled_at:too_soon / scheduled_at:too_far / scheduled_at:invalid	scheduled_at must be a valid ISO 8601 time between now and 72 hours out.
422	validation_error	attachments:too_large / attachments:total_too_large	One attachment over 10 MB decoded, or all attachments over 25 MB combined.
422	validation_error	routing_provider_not_configured	The pinned routing.provider isn’t attached to this project. Never silently rerouted.
422	validation_error	suppressed_recipient	A recipient is on the project’s suppression list; the message names the addresses.
422	permission_error	no_providers_configured	The project has no attached providers — attach one before sending.
429	rate_limit_error	daily_send_cap_exceeded	The Free tier’s 200/day ceiling — resets at 00:00 UTC.
429	—	—	Rate limit (600 requests/min per key) — honor the Retry-After header.

Batch requests respond 207 Multi-Status: each element of data is either a send object or one of these envelopes — check per element.

Handling advice

• 402 is a billing state, not a bug — surface it to whoever owns the plan; retrying won’t help until the month rolls over or the plan changes.
• 422 means the request will never succeed as-is — fix the payload; don’t retry blindly.
• Retry 429 and 5xx, with backoff and an Idempotency-Key so retries can’t double-send.