Errors

Every error uses one envelope:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "This batch costs US$0.0400 and your balance is US$0.0100. Load at least US$0.0300 more.",
    "docs_url": "https://docs.sms.xash.network/errors#insufficient_credits",
    "required": "0.0400",
    "balance": "0.0100",
    "shortfall": "0.0300"
  }
}

code is stable and machine-readable. message is for humans and may change. Extra context fields depend on the code.

Codes

Code	HTTP	Meaning	What to do
INSUFFICIENT_CREDITS	402	The batch costs more than your balance. The response includes the shortfall.	Top up, then retry.
MESSAGE_REJECTED	422	The body failed the content rules. Includes category and reason.	Rewrite as a service message, or contact support if it is one.
MODERATION_UNAVAILABLE	503	A new template could not be checked.	Retryable. Wait a moment and resend.
UNSUPPORTED_DESTINATION	per-recipient	The number is outside +263 / +27. Appears in rejected, not billed.	Remove the number.
INVALID_RECIPIENT	422 / per-recipient	The number does not parse.	Send E.164, e.g. +263771234567.
CHANNEL_NOT_AVAILABLE	400	The channel is reserved but not live (telegram, whatsapp).	Use sms.
ACCOUNT_SUSPENDED	403	Your account is suspended. The dashboard shows the reason.	Contact support.
RATE_LIMITED	429	Over 60 requests per minute.	Back off and retry. Batch recipients instead of looping single sends.
IDEMPOTENCY_CONFLICT	409	The Idempotency-Key was used with a different payload, or the original request is still running.	Use a fresh key, or wait and retry the identical request.
TOO_MANY_RECIPIENTS	422	More than 1,000 numbers in one call.	Split the batch.
VALIDATION_FAILED	422	A field is missing or malformed. The message names it.	Fix the request.
NOT_FOUND	404	No batch or message with that id on your account.	Check the id.

Partial rejection is not an error: a batch with some valid and some invalid numbers sends to the valid ones and lists the rest in rejected, unbilled.