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.
At a glance
Section titled “At a glance”| 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.
400 — the request can’t be read
Section titled “400 — the request can’t be read”request:invalid
Section titled “request:invalid”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.
content_encoding:invalid
Section titled “content_encoding:invalid”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.
401 — authentication
Section titled “401 — authentication”missing_api_key
Section titled “missing_api_key”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.
invalid_api_key
Section titled “invalid_api_key”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.
key_expired
Section titled “key_expired”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.
mode_mismatch
Section titled “mode_mismatch”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.
402 — quota
Section titled “402 — quota”monthly_quota_exceeded
Section titled “monthly_quota_exceeded”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.
throughput_quota_exceeded
Section titled “throughput_quota_exceeded”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.
free_team_limit
Section titled “free_team_limit”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.
scheduling_unavailable
Section titled “scheduling_unavailable”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).
404 and 405 — no such endpoint
Section titled “404 and 405 — no such endpoint”route_not_found
Section titled “route_not_found”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.
method_not_allowed
Section titled “method_not_allowed”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).
413 — the body is too large
Section titled “413 — the body is too large”body:too_large
Section titled “body:too_large”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”no_providers_configured
Section titled “no_providers_configured”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.
no_raw_mime_provider
Section titled “no_raw_mime_provider”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.
routing_provider_not_configured
Section titled “routing_provider_not_configured”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.
suppressed_recipient
Section titled “suppressed_recipient”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.
sender_domain:limit_reached
Section titled “sender_domain:limit_reached”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.
category:limit_reached
Section titled “category:limit_reached”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.
tags:limit_reached
Section titled “tags:limit_reached”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:*
Section titled “idempotency_key:*”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:*
Section titled “scheduled_at:*”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.
attachments:too_large
Section titled “attachments:too_large”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.
attachments:total_too_large
Section titled “attachments:total_too_large”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.
message:*
Section titled “message:*”These codes come from /v1/send/mime.
Nothing is stored when one of them is returned.
message:required. Cause. Themessagepart is missing, or the file in it is empty. Fix. Send the complete message, headers and body, as a file part namedmessage.message:not_a_file. Cause.messagearrived 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 themessagefile didn’t complete. Fix. Send the request again, with the sameIdempotency-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 noFromfield. 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.
sender:required
Section titled “sender:required”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:* and <field>:unsupported
Section titled “meta:* and <field>:unsupported”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.
Field errors
Section titled “Field errors”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,messageson batch,recipientsinmeta) fails astags:invalid,attachments:invalid,messages:invalid, orrecipients:invalid. - A reserved header (
headers:reserved) or a header name used twice in different case (headers:invalid): see theheadersfield in the request fields. - An attachment’s
content_typethat isn’t a media type (attachments.content_type:invalid), or acontent_idthat 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.
429 — slow down
Section titled “429 — slow down”daily_send_cap_exceeded
Section titled “daily_send_cap_exceeded”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
Section titled “Rate limited”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).
500 — Mailway failed
Section titled “500 — Mailway failed”server_error
Section titled “server_error”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.
Cookie consent
We may run ads on Google and Reddit. If we do, knowing whether they work needs your OK for one cookie each from them, used only to tie a signup back to the ad that brought it. Analytics here is cookieless either way, and declining changes nothing else.
Change your mind any time with "Cookie choices" in the footer. Details in the privacy policy.