Runbook: SMS codes not arriving

Phone-code sign-in went live on 26 May. Depot workers without a company email sign in with a six-digit code sent by SMS through Textbridge. If codes don't arrive, those people can't sign in at all, so treat many failures at once as SEV2.

1. One person or many?

• One person: check their number in the portal (People › the person). It must be in international format (+44…, +353…, +31…). The sign-in log shows whether a code was sent. Most single cases are a wrong number or a phone that blocks short codes. Support can handle these.
• Many people, one client: check whether the client's numbers are all in one country, then go to step 2.
• Many people, several clients: go to step 2 now and page the on-call engineer.

2. Is it us or Textbridge?

1. notifier logs: search for codes.send in the region. Are requests reaching notifier? If not, it is identity-service or the network.
2. Are we getting 202 Accepted from Textbridge? If not, check the API key and Textbridge's status page.
3. Delivery receipts: the receipt-lag alarm fires when receipts lag more than five minutes. Receipts saying undelivered for one country point at a carrier route.

3. What to do

• Textbridge is down or slow for a country: open an OPS ticket (SEV2), post on our status page under SMS codes, and call Textbridge's support line (number in the shared vault). Tell support so customers' site managers know; the workaround is local (paper sign-in at the gate) because there is no second provider. For one or two people, their own administrator can give a one-time code from the portal (ENG-1509).
• Our API key or account: Elif or Oskar can rotate it; the key is in the region's secrets.
• Rate limits: five tries per code, then a 15-minute wait. A person who mistyped five times waits; an administrator can't skip that.

What not to do

Don't switch an affected depot's people to passwords to get them in. They have no email, so they can't reset a password, and it leaves accounts behind.

Change history

Version	Date	Who	What
2	29 May 2026	Piet	Number formats after the Greenhollow pilot (SUP-891)
4	18 Jun 2026	Oskar	After OPS-33: status page, receipt-lag alarm
5	1 Jul 2026	Oskar	Status page is live
6	9 Sep 2026	Elif	A second SMS provider is postponed (waits on Textbridge's EU contract); still one provider