SMS error codes (mpbx-sms)
Raised by the SMS routes and the webhook endpoint (W3-SMS-01). Messages never contain provider
credentials, signatures or the text of a message; they name ids and field names at most. Codes
that start a message's life as a failure (MPBX-SMS-PROVIDER-REJECTED,
MPBX-SMS-PROVIDER-UNAVAILABLE and the provider's own short codes) are stored as the message's
error_code and carried by the sms.failed event. Guide: SMS.
| Code | Kind | Meaning | What to do |
|---|---|---|---|
MPBX-SMS-PROVIDER-NOT-FOUND | not_found | No such provider configuration in this company (another company's provider is invisible). | Check the id. |
MPBX-SMS-NUMBER-NOT-FOUND | not_found | No such number in this company. | Check the id. |
MPBX-SMS-CONVERSATION-NOT-FOUND | not_found | No such conversation in this company. | Check the id. |
MPBX-SMS-MESSAGE-NOT-FOUND | not_found | No such message in this company. | Check the id. |
MPBX-SMS-KIND-UNSUPPORTED | invalid_argument | The provider kind is not offered by this install (adapters are added per release). | Use one of the kinds GET /api/v1/sms/providers lists in available_kinds. |
MPBX-SMS-CONFIG-INVALID | invalid_argument | The provider's name, settings or credentials are not valid for its kind (wrong shape, a missing or too short secret). | Fix the named field; credentials are write-only and replace all stored ones. |
MPBX-SMS-NUMBER-INVALID | invalid_argument | A phone number is not in international format (+, then 7 to 15 digits, no leading zero). | Send +15550100; spaces, hyphens, dots and brackets are dropped. |
MPBX-SMS-NUMBER-TAKEN | conflict | The company already has this number. | Update the existing number instead. |
MPBX-SMS-PROVIDER-NAME-TAKEN | conflict | Another provider of the company has this name. | Choose another name. |
MPBX-SMS-FROM-NOT-OWNED | invalid_argument | The sending number is not one of the company's SMS numbers. | Add the number to a provider first (POST /api/v1/sms/numbers). |
MPBX-SMS-NUMBER-DISABLED | conflict | The sending number is switched off. | Switch it on, or send from another number. |
MPBX-SMS-PROVIDER-DISABLED | conflict | The number's provider is switched off. A queued message whose provider was switched off before it was sent fails with this code. | Switch the provider on. |
MPBX-SMS-BODY-INVALID | invalid_argument | The text is empty, longer than 1600 characters, or contains control characters other than line breaks and tabs. | Shorten or clean the text. |
MPBX-SMS-ROUTE-INVALID | invalid_argument | A routing target is inconsistent (a kind without an id, or an id with kind none), or the user or extension does not exist in the company. | Use {"kind":"none"} or a kind with an existing target_id. Queues and ring groups are accepted as ids until their objects exist. |
MPBX-SMS-PROVIDER-IN-USE | conflict | The provider still has numbers or messages, so it cannot be deleted (history is kept). | Switch it off instead (enabled: false). |
MPBX-SMS-NUMBER-IN-USE | conflict | The number still has conversations, so it cannot be deleted. | Switch it off instead. |
MPBX-SMS-CHANGED | conflict | The object changed between your read and your write (stale If-Match). | Read it again and retry with the new ETag. |
MPBX-SMS-CREDENTIALS-UNREADABLE | config | The sealed credentials of a provider cannot be opened (the master key was replaced without re-wrapping, or the row was damaged). Messages through it fail and its webhooks are refused. | Save the provider's credentials again. |
MPBX-SMS-PROVIDER-REJECTED | n/a (message error_code) | The provider refused the message for good (invalid destination, blocked, not allowed). Not retried. | Read the provider's own reason in its console; fix the number or the content. |
MPBX-SMS-PROVIDER-UNAVAILABLE | n/a (message error_code) | The provider could not be reached or kept failing; all attempts (5, with doubling delays from 30 seconds) are used up. | Check the provider's status and the credentials, then send again. |
MPBX-SMS-SEND-OUTCOME-UNKNOWN | n/a (message error_code) | A crash lost the result of a send and the provider (Telnyx, Plivo, Vonage, SMPP) cannot say whether it sent the message or drop a repeat, so it was not sent again. It may or may not have been delivered. | Check the provider's own log for the message; send again if it is not there. |
MPBX-SMS-WEBHOOK-UNAUTHORIZED | unauthenticated | A webhook call has no valid signature for this provider (missing, wrong secret, altered body, or a timestamp more than 5 minutes off). The answer carries no detail. | Check the provider's signing secret and that its clock is correct. |
MPBX-SMS-WEBHOOK-MALFORMED | invalid_argument | The signature was valid but the body is not what the provider's adapter expects. | Check the provider's webhook format setting. |
MPBX-SMS-WEBHOOK-TOO-LARGE | invalid_argument | The webhook body is larger than 64 KiB. | Reduce the batch size at the provider. |
MPBX-SMS-WEBHOOK-NOT-FOUND | not_found | The webhook address names no active provider (unknown, switched off, or the address was rotated). | Copy the current address from the provider's page. |
MPBX-SMS-WEBHOOK-RATE-LIMITED | unavailable | More than 600 calls in a minute to one webhook address. The provider should retry later. | Slow the provider down; retries are idempotent. |
MPBX-SMS-EGRESS-BLOCKED | n/a (message error_code, test-send) | The generic HTTP provider refused to call its configured address: private, loopback, link-local or metadata address, plain http without allow_http, or a name that resolves to such an address. Not retried. | Use a public https address; see generic HTTP provider. |
MPBX-SMS-CREDENTIALS-REQUIRED | invalid_argument | A change to a generic HTTP provider's settings would send its stored credentials somewhere else (another URL, method or header set, or a credential placed elsewhere in the request), or the stored credentials lack a field the new settings need. Stored credentials are write-only and only follow the destination they were entered for. | Send the credentials again in the same update; see generic HTTP provider. |
MPBX-SMS-TEST-RATE-LIMITED | rate limited (429) | The test console sent more than 10 messages in a minute for the company, or more than 3 to one recipient. It sends real messages, so it is limited (FU-SMS03-2). | Wait a minute (Retry-After: 60). |
MPBX-SMS-RECIPIENT-OPTED-OUT | conflict (409) | The recipient sent STOP (or was added by hand) for the sending number, so nothing was sent. Also the error_code of a queued message that a STOP stopped before it went out. Every refusal is logged (audit action sms.send_blocked). | Do not text this person from this number. If they want messages again they reply START, or an administrator removes the entry under SMS > Opt-outs; see the compliance checklist. |
MPBX-SMS-OPT-OUT-NOT-FOUND | not_found | No such opt-out entry in this company. | List the entries again. |
MPBX-SMS-CAP-REACHED | conflict (409) | A sending cap of the company, of the sending number or of the user is used up for the day or month (UTC). Nothing was sent. The first refusal of each period raises the sms.cap_reached event and an audit record. | Wait for the next period, raise the cap under SMS > Usage, or send from another number. |
MPBX-SMS-CAP-INVALID | invalid_argument | A cap is not acceptable: a number cap needs number_id, a user cap needs user_id, a company or recipient cap neither; an inbound cap is for the company or one number; the limit is 0 to 1000000000; the number or user must belong to the company; at most 500 caps. | Fix the cap. |
MPBX-SMS-CAP-NOT-FOUND | not_found | No such cap in this company. | List the caps again. |
MPBX-SMS-PRICING-INVALID | invalid_argument | The price list has a currency that is not a three letter ISO code in capitals, or a price outside 0 to 100000000 millionths; also a bad destination rule (prefix of 1 to 8 digits, listed once) or invoice (dates, currency, exchange rate). | Fix the price list, rule or invoice. |
MPBX-SMS-INVOICE-NOT-FOUND | not_found | No such carrier invoice in this company. | List the invoices again. |
MPBX-SMS-MMS-UNSUPPORTED | invalid_argument | The sending number's provider cannot send MMS (today: Twilio only). | Send from a number on a provider that supports MMS, or send plain text. |
MPBX-SMS-MEDIA-INVALID | invalid_argument | The media of an MMS are not acceptable: 1 to 10 public https addresses without credentials. | Fix the media_urls. |
MPBX-SMS-MEDIA-NOT-FOUND | not_found | The MMS media file does not exist, or its public address is wrong. | Upload the file again. |
MPBX-SMS-MEDIA-TOO-LARGE | invalid_argument | An uploaded MMS media file is empty or larger than 5 MB. | Send a smaller file. |
MPBX-SMS-MEDIA-TYPE-UNSUPPORTED | invalid_argument | MMS carries JPEG, PNG, GIF, MP4, MP3, AMR and PDF files; the upload has another type. | Convert the file. |
MPBX-SMS-MEDIA-STORE-OFF | unavailable | This install has no [files] object store, so MMS media cannot be kept. | Configure [files]. |