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

Code	HTTP	What fired	Fix class
`SENDER_ID_NOT_REGISTERED`	422	The `from` value is a custom alphanumeric sender ID with no registration row on the account for that channel	Register the sender ID first — see Register the sender ID
`SENDER_ID_NOT_APPROVED`	422	A registration row exists but its status is `pending`, `rejected`, or `expired` — not `approved`	Wait for approval, do not retry the send — see Wait for approval
`SENDER_ID_CHECK_UNAVAILABLE`	503	The approval lookup itself failed (a transient storage read) and the gate fails closed rather than let an unverified sender through	Retry with backoff — see Retry the check

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:

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+447700900123",
    "from": "MyBrand",
    "body": "Your receipt is ready."
  }'

An unregistered sender comes back with HTTP 422 and this body:

{
  "error": {
    "code": "SENDER_ID_NOT_REGISTERED",
    "status": 422,
    "message": "Sender ID \"MyBrand\" is not registered for this account. Submit it for approval in Settings → Sender IDs, or pick the platform default (Devotel) / one of your phone numbers.",
    "details": { "sender": "MyBrand", "channel": "sms" }
  }
}

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:

{
  "error": {
    "code": "SENDER_ID_CHECK_UNAVAILABLE",
    "status": 503,
    "message": "Sender ID approval check for \"MyBrand\" is temporarily unavailable. Retry in a moment, or switch to the platform default (Devotel) sender / one of your registered phone numbers.",
    "details": { "sender": "MyBrand", "channel": "sms" }
  }
}

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:

Upload the compliance documents the destination country requires (the per-country document list is in Country Compliance Requirements).
Submit the sender ID for the destination countries via POST /compliance/sender-id-registrations, or from Settings → Sender IDs in the dashboard.
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:

Retry the same request after a short backoff (seconds, not milliseconds — the check depends on normal service health to recover).
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).
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:

The sender ID value (exactly as sent in from) and the destination country.
The sender-ID registration state — copy the entry’s current status from Settings → Sender IDs or GET /compliance/sender-id-registrations.
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.

Sender-ID Registration — the registration endpoints and the pending → approved lifecycle.
Country Compliance Requirements — per-country sender rules and required documents.
Troubleshoot a pending number or Sender ID — the country-specific registration codes and India DLT.
Error Codes — the full sender-registration error table.

​Troubleshooting: alphanumeric sender ID rejected before send

​Match the code to its meaning

​Reproduce the rejection

​Fix per code

​Register the sender ID

​Wait for approval

​Retry the check

​Distinguish from the country-specific codes

​Escalation

​Related references