SMS billing and errors
Understand segment reservations, final charges, and stable SMS error codes.
Speko estimates GSM-7 or UCS-2 segments and atomically reserves sms.outbound_segment credits when a message is created. Available balance is ledger balance minus active reservations.
The reservation is captured when Telnyx accepts the message and adjusted idempotently if the final segment count differs. Cancellation, revoked consent, local rejection, and definitive pre-provider failures release it. Accepted messages are not refunded when a carrier later reports delivery failure.
Ambiguous timeouts and provider 5xx responses become submission_unknown; Speko retains the reservation and waits for a correlated webhook rather than risking a duplicate send. A reconciler resolves provider state or releases an unrecoverable hold after 72 hours. Late acceptance still creates one idempotent debit.
Inbound segments are debited idempotently but inbound storage is never rejected for insufficient credits. Final Telnyx cost is stored separately from retail credits for reporting.
Stable errors
| Code | Meaning |
|---|---|
PHONE_NOT_SMS_READY | Feature, number, profile, or current campaign readiness failed |
CONSENT_REQUIRED | No active campaign-scoped consent or conversation exception |
RECIPIENT_SUPPRESSED | Organization-wide STOP suppression is active |
RECIPIENT_TIMEZONE_REQUIRED | Proactive send has no resolvable IANA timezone |
INSUFFICIENT_CREDITS | Atomic segment reservation could not be made |
MESSAGE_NOT_CANCELABLE | Submission began or the message is terminal |
IDEMPOTENCY_CONFLICT | Key was reused with a different normalized request |
Treat submission_unknown as a status, not a signal to retry. Recover by reading the existing message with its original ID or waiting for a webhook.