Skip to main content

​
Note de langue

Lorsqu’une traduction n’est pas disponible, le contenu anglais est affiché comme solution de repli. Conservez les codes d’erreur, les chemins d’API et les blocs de code.

​
Troubleshooting: alphanumeric sender ID rejected before send

Orbit evaluates one alphanumeric-sender gate before the message is accepted for delivery. Send with a branded from (for example "MyBrand") that the account cannot prove, and POST /api/v1/messages/sms rejects the request synchronously — the message is never queued and never handed to the carrier. Three error codes come out of that gate: two permanent (fix the sender), one transient (retry). In the dashboard’s compose-SMS dialog the same gate runs client-side: the send button warns and refuses the submission instead of surfacing the error after the fact, with a shortcut to sender registration.

​
Match the code to its meaning

The first two are always HTTP 422 on the SMS send surface. They are permanent gates: sending the same request again returns the same code and burns your rate-limit budget without changing the outcome. Senders that skip this gate entirely — phone numbers (E.164, MSISDN, or a short code, whose ownership is proven separately), the fixed platform default "Devotel", and the shared platform sender pool — never raise these three codes. The gate applies when you type a custom alphanumeric brand into from.

​
Reproduce the rejection

Send an SMS with an alphanumeric from that is not in the account’s approved sender-ID list:
An unregistered sender comes back with HTTP 422 and this body:
A sender that is registered but still under review returns SENDER_ID_NOT_APPROVED with "status": "pending" (or "rejected" / "expired") inside error.details. When the approval check cannot be performed at all, the gate fails closed and returns HTTP 503 with SENDER_ID_CHECK_UNAVAILABLE:

​
Fix per code

​
Register the sender ID

SENDER_ID_NOT_REGISTERED means the value you sent has never been submitted for the account. Registration is tenant-owned and self-service:
  1. Upload the compliance documents the destination country requires (the per-country document list is in Country Compliance Requirements).
  2. Submit the sender ID for the destination countries via POST /compliance/sender-id-registrations, or from Settings → Sender IDs in the dashboard.
  3. Send again once the destination country entry reaches approved.
Registration is an idempotent upsert: re-submitting keeps countries already at approved and returns rejected / expired entries to pending for a fresh review. The full pending → approved / rejected / expired lifecycle is documented on Sender-ID Registration. If you do not need the brand on this send, switch from to an owned phone number or drop it and let the platform default apply — both paths skip the alphanumeric gate.

​
Wait for approval

SENDER_ID_NOT_APPROVED means a row exists but has not cleared review. The error.details.status field names the current state:
  • pending — awaiting review. Do not retry the send. Poll the entry with GET /compliance/sender-id-registrations (or watch Settings → Sender IDs in the dashboard) and retry the send only after it flips to approved.
  • rejected — the reviewer left a reason on the entry. Fix what it names, re-submit (the upsert returns it to pending), and wait.
  • expired — the approval lapsed. Re-submit for a fresh review.
Retrying the send while the status is pending never clears the gate — the send and the registration review are independent, so a retry loop only re-trips the 422.

​
Retry the check

SENDER_ID_CHECK_UNAVAILABLE (503) is the transient member of the family: the gate could not read the approval state and closed rather than guess. It is safe to retry:
  1. Retry the same request after a short backoff (seconds, not milliseconds — the check depends on normal service health to recover).
  2. Use exponential backoff with a retry budget, like the pattern in Troubleshooting: cooldown and rate-limit 429s (branch on res.status === 503 instead of 429).
  3. If 503s persist for more than a few minutes, check the status page before treating it as a sender problem. A persistent 503 on every sender points at platform health, not at your registration.

​
Distinguish from the country-specific codes

Brazil, Singapore, Saudi Arabia, and the UAE block unregistered alphanumeric senders with their own codes — MESSAGING_BR_SENDER_NOT_REGISTERED, MESSAGING_SG_SENDER_NOT_REGISTERED, MESSAGING_SA_SENDER_NOT_REGISTERED, and MESSAGING_AE_SENDER_NOT_REGISTERED — which fire when the destination country enforces registration even though a status on the account looks coherent. Those, plus the India DLT regime and the strict-mode SENDER_INVALID_FOR_DESTINATION 422s, are covered on Troubleshoot a pending number or Sender ID. The three codes on this page are the generic gate: they fire on any destination, before any country rule runs.

​
Escalation

Escalate to support when you have done the fix above and it cannot land — a registration stuck at pending well past the country’s normal lead time, a rejected reason you cannot resolve with the documents you hold, or 503s that outlast a status-page window. Include:
  1. The sender ID value (exactly as sent in from) and the destination country.
  2. The sender-ID registration state — copy the entry’s current status from Settings → Sender IDs or GET /compliance/sender-id-registrations.
  3. The message ID or request ID from a rejected send (error code and meta.request_id), and the timestamp with timezone.
A reviewer can pull the registration packet and the send attempt directly from those three.