Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sendmux.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Sending API uses the same error envelope as the Management API — same code/message/param/doc_url/retryable fields, same accumulated errors[] on validation failures, same X-Request-Id response header, same Retry-After semantics on 429/503. See the Management reference for the full envelope shape and the retryable + Retry-After policy. This page documents only the codes the Sending API actually emits.

​
Error response format

{
  "ok": false,
  "error": {
    "code": "insufficient_credits",
    "message": "A human-readable description of the error.",
    "param": "to.email",
    "doc_url": "https://docs.sendmux.ai/sending-api/errors#insufficient_credits",
    "retryable": false
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
param is only present when the error is tied to a specific request field. On accumulated validation failures, error.errors carries every issue — see Validation errors with multiple issues. Always include request_id (or the X-Request-Id response header) when contacting support.

​
Shared error codes

These codes are shared with the Management API. Their semantics are identical to the matching sections in the Management error reference.

​
authentication_required

HTTP 401 — The request has no Authorization header or the API key is invalid, expired, or revoked.

​
insufficient_permissions

HTTP 403 — The API key is valid but lacks the email.send permission.

​
invalid_parameter

HTTP 400 — A request field has an invalid format or value, or the JSON body failed schema parsing. The param field identifies the offending field; errors[] enumerates every issue when more than one is present.

​
missing_parameter

HTTP 400 — A required request field is missing from the body.

​
not_found

HTTP 404 — A referenced resource (for example, a from mailbox or a domain) does not exist or belongs to a different team than the one associated with your API key.

​
rate_limit_exceeded

HTTP 429 — You have exceeded the rate limit of 1800 requests per minute. The response carries a Retry-After HTTP header with the recommended wait in seconds; back off until then before retrying. retryable is true.

​
internal_error

HTTP 500 — An unexpected server error occurred. retryable is true. If this persists, contact support with the request_id.

​
Sending-specific error codes

​
insufficient_credits

HTTP 402 — Your team’s balance is too low to send this email (or batch). Top up your balance in the Sendmux app under Billing.

​
validation_error

HTTP 422 — The request body failed schema validation. Check the param field for the specific field that caused the error. Common causes:
  • Missing required fields (from, to, subject, html_body)
  • Invalid email addresses
  • Attachment file type not in the allowed list
  • Batch exceeds 100 messages

​
idempotency_conflict

HTTP 409 — Returned when the same Idempotency-Key request header is reused either (a) while the original request is still being processed (transient — wait briefly and retry to receive the completed result), or (b) with a request body that does not match the body fingerprint of the original request (permanent — fix the client to use a fresh key for the new request).

​
payload_too_large

HTTP 413 — The request body exceeds the maximum allowed size. Individual fields have limits: html_body and text_body are capped at 10MB each, attachments at 25MB total.

​
no_active_providers

HTTP 503 — No healthy delivery providers are configured for your team. Add and activate a provider in the Sendmux app under Accounts. retryable is true, but retrying will keep failing until you fix the provider configuration — this is a 503 because the request itself is well-formed.

​
service_unavailable

HTTP 503 — A downstream component needed to serve this request is temporarily unavailable. The response may carry a Retry-After header. retryable is true — back off and retry. If this persists for more than a few minutes, contact support with the request_id.