Skip to main content
The Sending API uses the same error envelope as the Management API: code, message, param, doc_url, retryable, accumulated errors[], X-Request-Id, and Retry-After on 429 or 503. This page documents only the codes the Sending API emits.

​
Error response format

{
  "ok": false,
  "error": {
    "code": "insufficient_credits",
    "message": "A human-readable description of the error.",
    "param": "to.email",
    "doc_url": "https://sendmux.ai/docs/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, the sender is not authorised for that key, or the mailbox is not active.

​
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[] lists 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, such as a from mailbox or 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 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 while the original request is still running, or with a request body that does not match the original body fingerprint. Wait and retry for an in-flight request. Use a fresh key for a different request.

​
payload_too_large

HTTP 413: The request body exceeds the maximum allowed size. html_body and text_body are capped at 25MB each. The full request body, including base64-encoded attachments, must be 25MB or less. Attachments are also bounded by the 10-attachment maximum.

​
no_active_providers

HTTP 503: Your team has no active sending account. Every team starts with the managed Amazon SES account active, so this usually means it was deactivated and no other provider is active. Reactivate the managed account, or add and activate a provider under Accounts. See Sending accounts. retryable is true, but retrying will keep failing until an account is active.

​
service_unavailable

HTTP 503: A required service is temporarily unavailable. The response may carry a Retry-After header. retryable is true, so back off and retry. If this persists for more than a few minutes, contact support with the request_id.