Skip to content

Errors

Every HTTP API error uses one envelope:

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

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

Field-validation failures carry the same envelope plus error.details, one entry per failing field; error.code mirrors the first, so a single-mistake request stays branchable on code alone:

{
"error": {
"type": "validation_error",
"code": "from:required",
"message": "Validation failed — `details` lists each failing field.",
"details": [
{ "field": "from", "code": "from:required" },
{ "field": "subject", "code": "subject:required" }
]
}
}

Batch requests respond 207 Multi-Status: each element of data is either a send object or one of these envelopes, so check per element. A persistence failure on one element surfaces as api_error / server_error — retry just that element. If a Free-plan limit runs out mid-batch, the elements past the limit surface the same monthly_quota_exceeded / daily_send_cap_exceeded envelopes a single send would get — the accepted elements before them still send.

The full contract, including these envelopes, is machine-readable at mailway.net/openapi.yaml.

Status type code
400 validation_error request:invalid · content_encoding:invalid
401 authentication_error missing_api_key · invalid_api_key · key_expired · mode_mismatch
402 quota_error monthly_quota_exceeded · throughput_quota_exceeded · scheduling_unavailable · free_team_limit
404 validation_error route_not_found
405 validation_error method_not_allowed
422 permission_error no_providers_configured · no_raw_mime_provider
413 validation_error body:too_large
422 validation_error routing_provider_not_configured · suppressed_recipient · sender_domain:limit_reached · category:limit_reached · tags:limit_reached · idempotency_key:* · scheduled_at:* · attachments:too_large · attachments:total_too_large · message:* · sender:required · meta:* and <field>:unsupported · field errors
429 rate_limit_error daily_send_cap_exceeded · rate_limited
500 api_error server_error

Every answer in this table uses the envelope on api.mailway.net and api.mailway.dev, whatever the request’s Accept header. An answer from the network in front of Mailway, such as a 502 or 503 while the API can’t be reached, may not carry the envelope. Retry it like a 500.

Three rules cover almost every case:

  • 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.

Cause. Mailway couldn’t read the request at all, so it never got as far as checking the fields one by one. The message is the same whatever the cause.

Fix. Compare the request’s headers and fields with openapi.yaml. Sending it again unchanged gets the same answer.

Cause. The request sends a Content-Encoding header (gzip or br), but the body doesn’t decode as that encoding.

Fix. Compress the body with the encoding the header names, or send plain JSON without a Content-Encoding header.

Cause. No Authorization header, or one that isn’t Bearer mw_live_… / Bearer mw_test_….

Fix. Send Authorization: Bearer mw_live_…. A key is its prefix plus 40 letters and digits — see what a key looks like.

Cause. The key doesn’t match any active key: mistyped, revoked, or belonging to a deleted project.

Fix. Create a new key in the console (the project’s Access section). Keys are shown once at creation and stored hashed, so a lost key can’t be recovered — only replaced.

Cause. The key had an expiry date and it has passed.

Fix. Create a new key. If you rotate on a schedule, note that expiry is per key, so overlap the new key before the old one lapses.

Cause. The key’s mode doesn’t match the host. A mw_test_… key was used on api.mailway.net, or a mw_live_… key on the sandbox host.

Fix. Match them: live keys on api.mailway.net, test keys on the sandbox. This binding is deliberate — it’s what stops a misconfigured environment variable from sending real mail from a test suite.

Cause. The plan’s monthly message quota is spent. Free plan only: every other plan soft-overages instead of blocking.

Fix. Upgrade the plan, or wait for the calendar month to roll over. A plan change lifts the limit immediately.

Cause. The plan’s monthly data-volume cap is spent, including the grace margin paid tiers get. Large attachments reach this before the message count.

Fix. Add a data-volume add-on or upgrade. Also worth checking whether the volume is intended — see the limits reference for each plan’s cap.

Cause. The team is on the Free plan, and the person who created it already has an older Free team. Only one Free team per person can send real mail (Limits & quotas). Test-key mail on api.mailway.dev isn’t affected.

Fix. An admin or someone with the Finance role chooses a paid plan for this team in the console, under Billing. Upgrading or deleting an older Free team lifts it too.

Cause. The send asked for scheduled_at, and the plan doesn’t include scheduled sends (Pro and up). Nothing is stored and no quota is used. In a batch, only that element gets the error.

Fix. Send without scheduled_at, or move to a plan that includes scheduling (Pro and up).

Cause. Nothing on api.mailway.net (or api.mailway.dev) serves that path: a typo, a missing /v1/, or an endpoint the API doesn’t have. The HTTP API is POST /v1/send, POST /v1/send/batch, and POST /v1/send/mime.

Fix. Check the URL against the send endpoint or openapi.yaml.

Cause. The path exists, but not for that method, for example a GET on /v1/send. The Allow header names the method it takes.

Fix. Send the request with the method in Allow (POST for all three send endpoints).

Cause. The request body is larger than the 25 MB limit. For a compressed body the limit applies once it is decompressed. On /v1/send and /v1/send/batch, base64 makes attachments a third larger, so a 25 MB request body holds at most 18.75 MB of them. On /v1/send/mime, the limit applies to the message file.

Fix. Send smaller attachments, or split a batch into smaller requests. For a raw message, host large attachments and link to them.

422 — the request can’t succeed as sent

Section titled “422 — the request can’t succeed as sent”

Cause. The project has no attached provider, so there is nothing to send through. Typed permission_error rather than validation_error because the payload is fine — the project isn’t ready.

Fix. Attach a provider to the project. Mailway is BYOK: it never sends through an account of its own, so a project with no provider genuinely cannot deliver.

Cause. A raw message was sent to /v1/send/mime, and none of the provider accounts attached to the project can carry one. That needs an account that sends over SMTP, an Amazon SES or Mailgun account (their APIs take a raw message), or an account an admin enabled re-encoding on for this project. Typed permission_error, like no_providers_configured: the message is fine, but the project isn’t ready for it.

Fix. Attach such an account in the project’s Routing section, ask an admin to enable re-encoding on one (SMTP mail through API providers), or send the mail as fields with POST /v1/send.

Cause. routing.provider pinned a provider that isn’t attached to this project. The message names the offending provider families.

Fix. Attach that provider, or drop the pin and let the project’s routing strategy choose. A pin is never silently rerouted — if you asked for a specific provider, Mailway would rather fail loudly than quietly send through a different one.

Cause. At least one recipient is on the project’s suppression list, from a hard bounce or a complaint. The message names the addresses.

Fix. Drop those recipients, or un-suppress the address in the console if you know the bounce is stale. Sending anyway is the wrong instinct: repeat hard bounces are exactly what damages a sending reputation, which is why the gate exists.

Cause. The from domain is new to this project and the plan’s sender-domain limit is already reached. Domains register on first use, so this fires on the first send from a new domain, not on setup.

Fix. Send from an already-registered domain, remove an unused one in the console, or upgrade. Note that subdomains count separately.

Cause. The project already has its maximum number of distinct category values. Categories are created on first use, so an unbounded or templated category value (an order ID, a timestamp) reaches the limit quickly.

Fix. Reuse an existing category or drop the field. Categories are meant to be a small, stable vocabulary — a per-mail identifier belongs in metadata, not here.

Cause. The send request carries a tag that is new to the project, and the project already has 1,000 distinct tags. Tags are created on first use, so a per-mail value in tags (an order ID, a timestamp) reaches the limit quickly.

Fix. Reuse existing tags. A value that identifies one mail belongs in metadata, which has no project-wide limit and comes back on every webhook event.

idempotency_key:invalid · idempotency_key:invalid_length

Cause. The Idempotency-Key header is malformed. It must be 12–40 characters of [A-Za-z0-9_-].

Fix. Use a UUID or a similar opaque token. Note the key scopes to the project and the first body wins: a retry with the same key returns the mail it first created rather than sending again. See idempotency.

scheduled_at:invalid · scheduled_at:too_soon · scheduled_at:too_late

Cause. scheduled_at must be an RFC 3339 date-time with an offset or Z, in the future, and no more than 72 hours out. A value without an offset, a date that doesn’t exist, or a relative value such as +1 hour or tomorrow is scheduled_at:invalid.

Fix. Send an absolute time with an offset: 2026-08-04T09:00:00Z or 2026-08-04T11:00:00+02:00. Mailway answers with the UTC time it names. For anything beyond 72 hours, hold the message in your own scheduler and submit it when it’s due.

Cause. One attachment exceeds 10 MB decoded. The limit is on decoded bytes. In the request body, the attachment’s base64 is a third larger.

Fix. Compress it, or host the file and send a link. Large attachments also hurt deliverability independently of this limit.

Cause. A message’s attachments together exceed 18.75 MB decoded. Base64 makes attachments a third larger, so a 25 MB request body holds at most 18.75 MB of them. A request over this limit is also over the body limit, which answers first, so the API returns body:too_large instead of this code.

Fix. Same as above. Note that up to 20 attachments are allowed, and inline images count toward both limits.

These codes come from /v1/send/mime. Nothing is stored when one of them is returned.

  • message:required. Cause. The message part is missing, or the file in it is empty. Fix. Send the complete message, headers and body, as a file part named message.
  • message:not_a_file. Cause. message arrived as a text field. Mailway takes the message only as a file, so nothing on the way can trim or convert it. Fix. Attach it as a file, for example with curl: -F 'message=@invoice-2042.eml;type=message/rfc822'.
  • message:invalid. Cause. The upload of the message file didn’t complete. Fix. Send the request again, with the same Idempotency-Key.
  • message:nul_byte. Cause. The message contains a NUL byte, which email doesn’t allow. Fix. Encode binary data as base64.
  • message:bare_cr_in_header. Cause. A header line contains a bare carriage return (one without a line feed after it). Two programs can disagree on where such a header ends. Fix. End every header line with CRLF.
  • message:header_dot_line. Cause. A line in the header block starts with a dot. Fix. Start every header line with a field name.
  • message:no_from. Cause. The message has no From field. Fix. Add one naming the author.
  • message:unparseable. Cause. Mailway couldn’t read the message as an email (RFC 5322). Fix. Send it as your mail library writes it: header fields, a blank line, then the body.

Cause. meta has no sender, and the message’s From field has no address Mailway can use as the envelope sender.

Fix. Put an address in the From field, or set sender in meta.

meta:invalid · meta:unknown_key · scheduled_at:unsupported · routing:unsupported · provider_options:unsupported

Cause. On /v1/send/mime, meta isn’t one JSON object (meta:invalid); it has a key the endpoint doesn’t know (meta:unknown_key, and details[].field names the key); or it sets an option this endpoint doesn’t take yet (<field>:unsupported).

Fix. Send meta as one JSON object with only recipients, sender, category, tags, metadata, and paused. For scheduling, routing, or provider options, send the mail with /v1/send.

Cause. Ordinary body validation: a missing from, a malformed address, no content, more than 50 recipients across to/cc/bcc, an over-long filename. error.details lists every offending field as { "field", "code" } — field is the dotted path (subject, to.1, attachments.0.filename), and error.code mirrors the first entry. On /v1/send/mime, field is a meta key (recipients, recipients.0, sender).

A code never carries a list index or a name you chose (a metadata key, a header name), so the set of codes is fixed: the second to address fails as { "field": "to.1", "code": "to:invalid" }, and a missing filename on the first attachment as { "field": "attachments.0.filename", "code": "attachments.filename:required" }. Some field errors in detail:

  • An address Mailway can’t put on a message, such as one with a comment (ada(work)@example.com), fails with the field’s code: from:invalid, to:invalid, recipients:invalid, and so on.
  • A JSON object where a list belongs (tags, attachments, messages on batch, recipients in meta) fails as tags:invalid, attachments:invalid, messages:invalid, or recipients:invalid.
  • A reserved header (headers:reserved) or a header name used twice in different case (headers:invalid): see the headers field in the request fields.
  • An attachment’s content_type that isn’t a media type (attachments.content_type:invalid), or a content_id that isn’t a valid message ID (attachments.content_id:invalid).
  • A subject over 989 characters (subject:too_long).

Every string is trimmed and an empty string counts as absent, so "" is refused wherever a value must be present: subject:required for the subject, metadata:value_invalid for a metadata value, and headers:invalid for a header value.

Fix. Read error.details and correct the payload. The full set of caps is in the limits reference. If you legitimately need more than 50 recipients per message, send in batches — and see the SES recipient cap for what providers do with large recipient sets.

Cause. The Free plan’s daily send limit. Typed rate_limit_error rather than a 402 on purpose: it’s a limit that resets, not a plan you’ve outgrown.

Fix. Wait — it resets at 00:00 UTC — or upgrade for a higher limit.

rate_limited

Cause. Too many requests. The budgets are per key:

Endpoint Limit
POST /v1/send and POST /v1/send/mime, together 600 requests/min per key
POST /v1/send/batch 6 requests/min per key (100 messages each, so the same 600 messages/min)

Requests without a well-formed Authorization: Bearer mw_… header fall back to a much tighter per-IP bucket, so a malformed Authorization header can look like a rate-limit problem when it’s really an auth problem.

Fix. Honor the Retry-After header and back off. If you’re sending in bulk, POST /v1/send/batch moves 100 messages per request and is the cheaper path against the same message budget. To avoid the 429 altogether, pace yourself from the RateLimit header every response carries (rate-limit headers).

Cause. Something failed on Mailway’s side. The body carries no details of the failure. On a batch, the same code in one element’s slot means only that element couldn’t be saved.

Fix. Retry with backoff. On /v1/send and /v1/send/mime, send the same Idempotency-Key, so a retry can’t send the mail twice. If it keeps happening, write to hello@mailway.net with the time of the request.