Third-party dependency failures
Dependency failure

Twilio Outage: API 5xx vs Carrier Delivery Failures, and How to Detect Each in Your Logs

By Sazabi Team

Failure facts checked on the vendor’s docs on Nov 8, 2026.

Twilio failures come in two layers. The first is Twilio's API returning errors when you try to send. The second is the message or call being accepted, then not delivered. Dashboards that only count API errors see the first layer and miss the second.

Layer one: API errors

Twilio's own documentation calls 500 and 503 server-side problems and says they should be rare. Error 20500 is the one you will see in logs. Twilio describes it as an error in server handling or a timeout in the API. If you see a consistent pattern, the docs tell you to check the status page and, if the page is silent, contact support with details of the failing requests.

For retries, Twilio lists 429, 500, 502, 503 and 504 as retryable, with exponential backoff and a limit of roughly three to five attempts. It adds that you should honor Retry-After on a 429 and should not retry other 4xx errors. It also warns against retrying forever: frequent 5xx may indicate a systemic problem to escalate.

The duplicate-message trap

Twilio separates safe from unsafe retries. GET and DELETE can always be repeated. Some POST requests, such as buying a specific number or hanging up a call, end in the same state however often you send them. Sending an SMS or placing a call does not. After a 500 on those requests, a retry may deliver two messages or ring a customer twice.

A practical guard: before retrying a send after a 5xx, list recent messages to the same number with the same body and skip the retry if one exists, or keep your own send ID and dedupe on it.

Layer two: delivery failures

Accepted does not mean delivered. Twilio's SMS debugging guide says a message marked Undelivered or Failed means Twilio received a delivery receipt from a carrier saying it was not delivered. During a carrier incident that share can climb while the API still returns 201 for every request. Twilio's status page has a separate Carrier Network section for exactly this, and you can set location preferences there.

Example: an API outage and a carrier problem

This is an example, not output from a real project.

2026-11-08T15:20:11Z op=messages.create to_cc=US status=500 code=20500 attempt=1
2026-11-08T15:20:13Z op=messages.create to_cc=US status=201 sid=SM_example1 attempt=2
2026-11-08T15:44:02Z callback sid=SM_example2 to_cc=GB status=undelivered
2026-11-08T15:44:09Z callback sid=SM_example3 to_cc=GB status=undelivered
2026-11-08T15:44:10Z callback sid=SM_example4 to_cc=US status=delivered

The first pair is an API error that cleared on retry. The second set has no API error at all. UK messages are ending undelivered while US messages are fine, which points to a route problem rather than your code.

What to log and measure

Log both layers.

  • At send time: operation, status, error code, attempt, destination country, message SID.
  • At status callback time: SID, final status, destination country, error code if present, and time from send to callback.

Then measure:

  • The share of sends answered with 5xx. Twilio says these should be rare, so a few percent for five minutes is already unusual.
  • The share of messages ending undelivered or failed, per destination country, compared with the same hour on previous weeks.
  • The count of sends with no callback after your normal delay. A silent callback endpoint can mean delivery problems or a webhook problem on your side.

Responding

  1. Confirm on the Twilio status page, in the right section: product or carrier network.
  2. Stop automatic retries of sends when the failure is on the 5xx layer, or cap them at three.
  3. For a carrier problem, switch the affected country to a backup channel such as email or push if you have one.
  4. Keep SIDs and timestamps for your support case.

Checklist

  • Send logs have status, code, country and SID.
  • Callbacks are stored and compared per country.
  • Sends carry your own dedupe ID.
  • Status notifications are subscribed with carrier locations set.

Read vendor degradation detection and third-party failure monitoring. The Twilio integration page lists how logs reach Sazabi, and the webhook gaps guide covers silent callbacks. Sazabi can watch both layers and open one investigated issue.

Twilio outages facts

  • Error 20500: Twilio error 20500 means the API hit a server handling error or a timeout, and a consistent pattern of 500s should be checked against the Twilio status page before contacting support. (Twilio docs, accessed Nov 8, 2026)
  • Retries and duplicate messages: GET and DELETE requests are safe to retry, but retrying a POST that sends an SMS or starts a call after a 500 can make a customer receive multiple messages or calls. (Twilio docs, accessed Nov 8, 2026)
  • Retry guidance: Twilio recommends retrying 429, 500, 502, 503 and 504 with exponential backoff and a maximum of about 3 to 5 attempts, honoring Retry-After, and not retrying other 4xx. (Twilio docs, accessed Nov 8, 2026)
  • Systemic 5xx: Twilio says 5xx errors should be rare, and frequent ones may indicate a systemic problem to escalate to Twilio Support rather than retry indefinitely. (Twilio docs, accessed Nov 8, 2026)
  • Status page subscriptions: You can subscribe to Twilio incident and update notifications and set carrier network location preferences in the Carrier Network section of the status page. (Twilio docs, accessed Nov 8, 2026)

With Sazabi

The Sazabi agent automatically sets up sensors for your project and maintains them over time. When your code calls Twilio, it watches a question like this one:

Tell me when the share of Twilio API calls answered with a 5xx is well above its usual level, and when the share of messages ending undelivered or failed is well above its usual level for the same destination country.

When the answer turns abnormal, Sazabi investigates and opens an issue. Vendor degradation covers the signal behind it.

Frequently Asked Questions

What is Twilio error 20500?

It is an internal server error from the Twilio API, generally an error in server handling logic or a timeout. Twilio says to check its status page if you see many, and contact support if the page shows nothing.

Is it safe to retry a failed Twilio SMS request?

Not blindly. Twilio says retrying a POST that sends an SMS or starts a call after a 500 can make a customer receive multiple messages or calls. Check whether the first request created a message before sending again.

How many times should I retry a Twilio request?

Twilio suggests a maximum of about 3 to 5 attempts with exponential backoff for 429, 500, 502, 503 and 504, and says not to retry other 4xx errors, which need a code or configuration fix.

Why does Twilio status have a carrier network section?

Message and call delivery depends on carrier networks as well as Twilio. The status page lets you set carrier network location preferences so notifications match where you send traffic.

Sources

  1. Meaning of 20500, check status page, idempotent versus non-idempotent requests (accessed Nov 8, 2026)
  2. Retry strategy, retryable status codes, Retry-After on 429 (accessed Nov 8, 2026)
  3. 500 and 503 are server side, retry with backoff, systemic problems escalated to support (accessed Nov 8, 2026)
  4. Undelivered and Failed statuses come from carrier delivery receipts; no record at all means an application or API error (accessed Nov 8, 2026)
  5. Subscribing to incident notifications, carrier network section and location preferences (accessed Nov 8, 2026)
Send your Twilio logs to Sazabi