Twilio queue overflow error: how large is the queue?

Question

Twilio's Message resource has a "status" property that indicates whether a SMS message is "queued", "sending", "failed", etc. If a Message instance failed to deliver, one possible error message is "Queue overflow". In the Twilio documentation, the description for this error case is: "You tried to send too many messages too quickly and your message queue overflowed. Try sending your message again after waiting some time."

Is the queue referenced in error code 30001 an instance of this resource? https://www.twilio.com/docs/api/rest/queue

Or is the queue (in the case of a 30001 error code) something that Twilio maintains on their end? If Twilio does throttling behind the scenes (queueing SMS messages per sending phone number), what is the size of that queue? How much would we have to exceed the rate limit (per phone number) before the queue overflow referenced in error code 30001 occurs?

Macdonell

Answer 1

Emily, message queue is not related to the queue resource you linked to above and it is something maintained on our end.

Twilio can queue up to 4 hours of SMS. This means, we can send out 1 sms per second, if there are more than 14,400 messages in the queue, all the messages queued up after will fail with 30001 error queue overflow and will not be sent. This info is for Long Code numbers. The link above explains processing for other scenarios.

A few suggestions to avoid the error:

• Keep messages to at most 160 characters if possible. But if not possible, calculate how many SMS messages each message will be (if you are not sure you can always send 1 test message and see how much you are charged for that message).
• Based on the assumption that your messages is 160 characters, throttle the sending rate to 3600 messages per hour (1 messaage/sec * 60 sec/min * 60 min/hr).

Please let me know if you've got any other questions.

Archegonium

Thanks Megan! You mentioned Twilio can queue up to 4 hours of SMS. Is this queue maintained per long code or is the queue shared among all the codes owned by an account? In scenario A, I buy 10 long codes and round robin. Should I throttle the sending rate to 60 messages/minute as the throughput of all long codes combined, or can each long code send at a rate of 60 messages/minute without incurring a 30001 error? In scenario B, I add 10 short codes and send SMS from both the long and the short codes. Do messages sent from all the short and long codes in my account live in the same queue? – Macdonell

Sorry for the delay Emily. I believe that is on a per number basis - regardless of the scenario A or B. – Archegonium

Answer 2

Each of the Twilio phone numbers(senders) has a separate queue in which 14400(4 hr x 60 min x 60 sec) message segments can be queued. 1 segment is sent in one second.

• What is a message segment?

A message segment is not a complete message but a part of a message. Normally SMS is sent in terms of message segments and all message segments are combined on the user’s mobile to create the actual SMS.

• Twillio message segment config:

1 character = 8 bits(1 byte)

GSM encoding = 7 bit per character

UCS-2 encoding = 16 bit per character

Data Header = 6 bytes per segment

Summary: Each character takes 8 bits, If GSM encoding is used, each character will take 7 bits or if UCS-2 encoding is used, each char will take 16 bits. In the case of multiple segments, 6 bytes per segment will be used for data headers(responsible for combining all segments of the same SMS on user mobile)

• Character per Message Segment:

GSM encoding when single segment = (140 char bytes x 8 bits)/ 7 bits = 160 characters

UCS-2 encoding when single segment = (140 char bytes x 8 bits)/ 16 bits = 70 characters

GSM encoding when multiple segment = ((140 char bytes - 6 header bytes) x 8 bits)/ 7 bits = 154 characters

UCS-2 encoding when multiple segment = ((140 char bytes - 6 header bytes) x 8 bits)/ 16 bits = 67 characters

Based on what encoding is used(check via Twilio Admin) for your message, you can calculate how many SMS can be in the queue at a time.

References:

1. https://support.twilio.com/hc/en-us/articles/115002943027-Understanding-Twilio-Rate-Limits-and-Message-Queues
2. https://www.twilio.com/blog/2017/03/what-the-heck-is-a-segment.html

Tokharian