Errors
Every error comes back in the same envelope, and the HTTP status code matches the error type.
Last updated
Error envelope
{
"error": {
"type": "validation_error",
"message": "At least one of html or text is required.",
"request_id": "req_abc123",
"details": [
{ "field": "", "message": "At least one of html or text is required." }
]
}
}The details array holds one message per field. You get it on validation errors and on some others with a stable reason, such as a refused send. If an entry has a code, branch on the code, not the message. retry_after is the number of seconds to wait. It shows up on rate limit errors and when you retry with an idempotency key that is still running.
The message_id field appears only on a reconciliation_required error. It names the tracking message the cut-off attempt left behind. Fetch that message to see what happened, or quote it when you contact support. Don't retry the send. The original may already have gone out, which is why this error is a 409: the SDKs never retry it for you.
Error types
| Type | Status | Description |
|---|---|---|
| validation_error | 422 | Invalid request body or parameters. |
| authentication_error | 401 | Missing or invalid API key. |
| authorization_error | 403 | The key is missing the scope, or can't reach this resource. |
| quota_exceeded | 403 | A plan, trial, or fixed limit is reached (mailboxes, sends, subscribers, team members, API keys, and others). Waiting does not lift it. |
| not_found | 404 | The resource or API route doesn't exist. |
| conflict | 409 | A request with the same idempotency key is still running, or the resource is already in progress (for example a mailbox import that is already running). An idempotency key reused with a different body also has this type, with status 422. |
| reconciliation_required | 409 | An earlier send attempt was cut off and nobody knows if it went out. Don't retry. Read message_id first, because the original may already have been sent. |
| rate_limit_error | 429 | Rate limit exceeded, a sending limit reached (the organization's daily limit, a per-mailbox limit, or the halved limit while sending is slowed down), or the per-mailbox export cap of 24 per 24 hours reached. |
| internal_error | 500 | Unexpected server error. |
| internal_error | 503 | The mail server is briefly unreachable, for example during a restart. Retry after the seconds in the Retry-After header. The SDKs do this for you on reads. |
Unknown API routes
An unmatched path under /api/v1/ returns the same JSON error envelope as any other API failure, never the website's HTML error page. Quote the request ID if you report a missing or mistyped endpoint.
{
"error": {
"type": "not_found",
"message": "API route not found.",
"request_id": "req_abc123"
}
}Quota exceeded error
When you hit a plan, trial, or fixed limit, the API returns a 403 with type quota_exceeded. The message states your usage and the limit, and the limit object gives the same values as fields: resource, used, limit, and scope (trial, plan, or fixed). A trial or plan limit also carries reason and action_url. A fixed limit, such as 50 API keys, is the same on every plan and has no action. Storage values are in bytes.
{
"error": {
"type": "quota_exceeded",
"message": "Active subscriber limit reached (100). End the trial early from Billing to lift it.",
"request_id": "req_abc123",
"reason": "trial_capacity",
"action_url": "https://shipmail.to/billing?org=org_abc123",
"limit": {
"resource": "audience_subscribers",
"used": 100,
"limit": 100,
"scope": "trial"
}
}
}Sending limits that lift with time, such as the daily limit or the hourly limit, stay 429 rate_limit_error. A send past the organization's daily limit has details[].code daily_limit, both for the free trial's 100 recipients a day and for the plan's daily limit. The limit counts recipients, so a message to 3 people uses 3. The codes daily_limit_ramp_up and hourly_limit_ramp_up are no longer returned; a client that still checks for them can treat them like daily_limit.
See Plan limits for quotas by plan.
Refusals the owner can fix
The organization owner can lift some refusals in Shipmail. These keep their usual type and status, so your error handling still works, and add two fields: reason and action_url, a Shipmail page where the owner reviews and confirms.
{
"error": {
"type": "quota_exceeded",
"message": "Mailbox limit reached (3/3). Your Team plan trial includes 3 mailboxes.",
"request_id": "req_abc123",
"reason": "trial_capacity",
"action_url": "https://shipmail.to/billing?org=org_abc123"
}
}| Reason | Where | Description |
|---|---|---|
| owner_confirmation_required | POST /v1/domains/register, 403 authorization_error | An agent credential asked to buy a domain. Agents never pay. The owner checks the price and confirms. |
| subscription_required | POST /v1/mailboxes, 422 validation_error | The organization has no plan yet. |
| trial_capacity | Any plan limit, 403 quota_exceeded | The trial's own limit is reached. Ending the trial early lifts it and charges at once, so ask the owner first. |
| purchased_capacity | Any plan limit, 403 quota_exceeded | The paid plan is full. The owner adds capacity or changes plan. |
Send action_url to the owner. Once they confirm, retry with a new idempotency key, because the old key returns the stored refusal. The TypeScript SDK exposes the fields as error.reason and error.actionUrl, the Python SDK as error.reason and error.action_url. Both SDKs expose the limit as error.limit. The CLI prints the link and the limit, and MCP tool errors include both.
Rate limit error
A 429 response includes a Retry-After header and a retry_after field in the error body:
{
"error": {
"type": "rate_limit_error",
"message": "Rate limit exceeded. Try again later.",
"request_id": "req_abc123",
"retry_after": 12
}
}