Guides

Errors

Every failure has the same shape, a stable machine-readable code, and a request id you can quote to support.

The envelope

Failures are wrapped in an error object. Branch on code — never on the message, which is written for humans and may be reworded at any time.

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Wallet balance 0 XOF is below the 23700 XOF required.",
    "retryable": false,
    "detail": {},
    "request_id": "01K3F7XQZ8V2N4M6P8R0T5CJWE"
  }
}

code — a stable identifier. This is what your integration should switch on.
message — human-readable, and not stable. For internal errors it is always generic: no exception text, no SQL and no stack trace ever crosses the boundary.
retryable — whether retrying the identical request could plausibly succeed. Published so you do not have to guess.
detail — machine-readable context, always an object. It is empty rather than absent when there is nothing to add.
request_id — identifies this exact request in SMSend's logs. Present on every error, including 4xx.

Correlating with support

The same identifier is returned as a header on every response, successful or not. Log it. Quoting it turns a support conversation about a failure that happened yesterday into a single lookup.

X-Request-Id: 01K3F7XQZ8V2N4M6P8R0T5CJWE

What to retry

Only three errors are marked retryable: a request still in flight under the same idempotency key, a rate limit, and an internal error. Everything else will fail again in exactly the same way, and retrying it just spends your rate limit.

Payment failures use 402 rather than 422 precisely so that they are easy to separate from malformed requests. A client that retries a validation error is wasting requests; a client that retries an insufficient-funds error in a loop is doing something worse.

Every error code

The complete published vocabulary. New codes can be added, so handle an unrecognised one as a generic failure rather than crashing.

Code	Status	Retryable	Meaning
`UNAUTHORIZED`	401	No	No key, a malformed key, a wrong secret, a revoked or expired key, or a suspended account. All indistinguishable by design.
`FORBIDDEN`	403	No	The account or the caller is not permitted to perform this operation.
`INSUFFICIENT_SCOPE`	403	No	The key is valid but does not carry the scope this endpoint requires. The scope is named in the detail.
`ACCOUNT_SUSPENDED`	403	No	The account is suspended and cannot use the API.
`VALIDATION_FAILED`	422	No	The request was malformed: a missing or invalid parameter, a bad idempotency key length, a rejected webhook URL, or an unsupported method or content type.
`NOT_FOUND`	404	No	No such resource — including one that belongs to another account, which is deliberately indistinguishable from one that never existed.
`UNSUPPORTED_VERSION`	400	No	The version in the path is not supported. The supported versions are listed in the detail.
`IDEMPOTENCY_KEY_REQUIRED`	422	No	A batch was submitted without an Idempotency-Key header.
`REQUEST_IN_PROGRESS`	409	Yes	Another request with this idempotency key is still in flight. Wait for the stated interval and retry.
`IDEMPOTENCY_KEY_REUSED`	409	No	This idempotency key was already used for a request with a different body. Use a new key.
`INSUFFICIENT_FUNDS`	402	No	The prepaid wallet cannot cover the quoted amount.
`CREDIT_LIMIT_EXCEEDED`	402	No	The postpaid accrual would exceed the account's credit limit.
`WALLET_IN_DEBIT`	402	No	The wallet is in debit and cannot be spent from.
`BATCH_EMPTY`	422	No	The batch contains no recipients.
`BATCH_BODY_EMPTY`	422	No	The message body is blank once trimmed.
`SCHEDULE_INVALID`	422	No	The scheduled time is in the past, or the timezone is not a valid IANA identifier.
`SENDER_NOT_APPROVED`	422	No	The sender is not approved for this account.
`RATE_LIMITED`	429	Yes	The key's request limit was exceeded. Wait for the interval in Retry-After.
`CONFIGURATION_ERROR`	500	No	Pricing or routing is not configured for this request. Contact support; retrying will not help.
`INTERNAL_ERROR`	500	Yes	An unexpected failure on SMSend's side. Quote the request id to support.

Why other people's resources are 404

Requesting a batch, message or webhook that belongs to another account returns 404, not 403 — the same answer as a resource that has never existed. A 403 would confirm that the identifier is real, which turns the endpoint into a way of testing whether particular ids exist.