We are excited to announce a number of upcoming improvements in Messaging Error Visibility which will empower you to better understand your Twilio integration. These changes will be gradually rolled out between February and April of 2024.
Visibility on Message Creation API Errors
- How things have worked historically
- Upcoming changes
- Things that aren’t changing
- How much of a change should I expect?
- What do I need to do?
- Additional Logging Improvements
Visibility on Message Creation API Errors
How things have worked historically
When you make a POST to the Programmable Messaging API to create a new message, the Twilio API typically responds with 201 Created and returns a Twilio Message SID for the message so you can track it further. Those messages are visible in the SMS logs and Messaging Insights in the Twilio Console as well as when you list messages via the Programmable Messaging API.
However, when POSTs to create messages encounter an error, Twilio’s API returns a HTTP status code 400 and includes a specific 5-digit Twilio error code to help you understand what went wrong with the request. The messages that returned a 400 response have not historically been visible in the console nor when you make a list request to the API.
We want to give you access to all of Twilio’s great tooling to help you understand all of your messages. This improved visibility will be rolling out on an account by account basis in two phases:
Phase One - We will begin recording HTTP 400 Errorful message creation attempts
We will now record all message creation attempts on your account, including both successful POSTs (201 response) and failed POSTs (400 response). This means that the errorful message creation attempts (400 responses) will become visible to you in your Messaging Logs and Insights as well as when you list messages on the API.
This empowers you to better troubleshoot errors that you may not be tracking well today. We will be deploying this new functionality gradually to Twilio accounts beginning in mid-February, 2024.
There will be banners at the top of Messaging Logs and Insights pages indicating whether or not your account has been enabled with the new capability.
Phase Two - We will enable these synchronous message creation errors in the console Error Log experience
You will be able to set alerts and receive alerts on all error events related to your attempts to create messages via the Error Log in the Twilio Console.
Things that aren’t changing
To minimize disruption and ensure that you don’t need to make code changes in your Twilio integration these important things will stay the same:
- The error response from the Twilio API will stay the same; the status code will still be 400 and the body of the response will remain unchanged. Unfortunately, this means that you still won’t receive the Message SID with these error responses; but they will be available when listing messages via the API.
- We won’t be sending new status updates for synchronous API failures to your webhook receiving infrastructure. As always, the initial status of the message is returned in the synchronous response to your POST, only subsequent updates to a messages status result in status callbacks and EventStream events.
How much of a change should I expect?
As with most technical things, the answer is, "it depends":
- If you are already closely tracking the response status codes from Twilio’s API, you know how many 400 responses you receive and can anticipate how much that will change the views on Messaging Insights.
- If you always create messages using a Messaging Service (specifying a MessagingServiceSid parameter in your request), your messages are quickly accepted by the API before most processing is completed and HTTP 400 synchronous errors are very rare.
- If your integration doesn’t fall into either of those categories, you will begin seeing the amount of message creations that result in a HTTP 400 synchronous error. At first this change will be visible in your Messaging Logs and Insights as well as when you list messages in the API. Once the Error Log experience rolls out to your account, you might get alerts for these errors if you have alerts configured.
What do I need to do?
We strongly recommend reviewing your Messaging Insights in the console on a regular basis. Here in the Delivery & Errors view you can find breakdowns of your messages by final status and error code. You can further drill down to find lists of recent messages for each given error code and understand why these message creation attempts are failing.
Each Twilio error code has a description and troubleshooting guidance in the Twilio Error Dictionary. If after following these troubleshooting suggestions you still see errors that cannot be resolved and you have questions about why they are occurring, you can contact support for additional guidance.
Additional Logging Improvements
Coverage in Error Log and Alerts
We’re increasing error coverage in the console Error Log tooling to ensure that it captures all message errors. We have identified specific error scenarios that result in failed or undelivered messages, and even though status callback webhooks were sent, they were not previously included in the Error Log and Alerting tooling. We will be improving the system by including these errors so you have full visibility on them and can set Error Alarms for console, email, and/or webhook notifications.
Inbound message visibility
Twilio does not generally allow receiving inbound One Time Passcode (OTP) messages on Twilio numbers. This prevents abuse of Twilio numbers. Previously, these inbound messages were filtered before being processed onto your Twilio account. In order to provide better visibility for all inbound traffic, Twilio will allow you to see these messages, but will be redacting the passcode itself and setting a failed status with error code 30038.