What the Provisioning API Doesn’t Tell You: SGP.22 eSIM Failure Modes From a Live Retail Operation

The mistake behind most eSIM provisioning failures: treating provisioning as one state

The single most useful thing to understand is that profile delivery and profile enablement are two independent axes, and most tooling collapses them into one.

The GSMA specifications are perfectly clear about this. A profile on an eUICC is Enabled, Disabled or Deleted. Downloading and installing a profile does not enable it. These are separate operations with separate results.

The problem is that commercial provisioning APIs sit on top of that, and their vocabulary is not the specification's vocabulary. The platform we buy from returns an order lifecycle with statuses along these lines:

The two axes a provisioning API reports separately, and the combination that generates the support volume.

Read that table again with an operational eye. IN_USE is not a health indicator. It tells you an installation happened at some point. It says nothing about right now.

The combination that generates the most support volume is IN_USE plus DISABLED: the profile is installed on the handset, the customer can see the plan sitting in their settings, and the line is switched off. Consumption is at or near zero. From the operator's side everything looks like a completed, successful order. From the user's side there is no internet.

GOT_RESOURCE, by contrast, looks alarming and almost never is. It is the normal resting state of an order that has not been installed yet. We spent time treating it as a fault before working out that it is simply the beginning of the lifecycle.

The lesson generalises: any status field that describes an event that happened once should never be wired to an alert that implies a current condition.

Failure mode 1: installed and switched off

Installing an eSIM and activating a line are two actions, separated in the handset UI by several screens and, on some devices, by a plan-labelling step that users abandon halfway through. A profile that is downloaded but left disabled is not an error state anywhere in the stack. It is a valid, specified condition.

For a retail operation, this is the number one cause of "I have no internet". It is also the hardest to diagnose remotely, because the customer's honest description, "I installed it, it's right there on my screen", is true and points away from the actual problem.

What made it tractable was reading both axes on every enquiry, in this order:

1. Is the profile installed at all? (IN_USE or not)
2. Is the line enabled?
3. Has any data been consumed?

Zero consumption with an installed profile is close to diagnostic on its own. If a profile has been installed for hours and moved no bytes, the line is off, roaming is off, or data is off, rather than a network fault in most cases.

A second-order failure came from our own code. We cached the last known profile state on the order record and read the cached value when a customer wrote in. When the cache was stale, support was reading a state that had been true yesterday and telling people to reinstall a profile that was working. A cached lifecycle state presented as current is worse than no state at all, because it is confidently wrong, and the advice it produces destroys a working installation.

Failure mode 2: the profile is fine and the phone says nothing

The second recurring pattern is a data-only profile behaving exactly as designed and the user reading the handset as broken.

A data-only profile has no voice or SMS registration. Depending on the handset, the OS version and which line is set as primary, the status bar can show no operator name and no bars while the data connection is working normally. A traveller who has spent twenty years reading signal bars as "connected" will report this as a dead SIM, and no amount of backend telemetry contradicts them, because the backend is right: the profile is enabled and passing traffic.

APN behaviour compounds it. The correct APN varies by destination and by the underlying operator the profile roams on, and a handset carrying over a manual APN from a previous SIM will attach and then fail to pass traffic, which looks identical to a coverage problem.

Neither of these is a bug. Both are cases where the user-visible signal and the system-visible signal disagree, and the operational answer is not better backend monitoring. It is telling the user in advance what the phone is going to look like.

Failure mode 3: the profile is perfect and the delivery is empty

Worth including because it is the easiest to miss and the most embarrassing.

For roughly two weeks our transactional emails went out with empty bodies. The QR code never reached anyone. Provisioning was flawless: profiles allocated, RELEASED, ready to install. The send API returned success on every call.

The cause was a line in the function that assembled the MIME message. It filtered out empty strings, which removed the mandatory blank line between headers and body required by RFC 5322 section 2.1. The base64 body was then parsed as a continuation of the header block and discarded. No component in the chain raised an error, because at every individual step nothing had gone wrong.

The generalisable point for anyone running automated provisioning: your success metric has to be end to end, and it has to be measured on the far side of every hand-off. "The API returned 200" is not delivery. In our case the only honest test was to send a real order to a real mailbox and read it back over IMAP, which is now what happens on a schedule.

What engineers actually search for

One way to check whether a topic is under-served is to look at what people type into a search box. The table below is UK search volume from Google's keyword planner data, pulled on 2 September 2026.

UK search volume, September 2026. Source: Google keyword planner data via DataForSEO.

The architecture terms are the ones the industry writes about. Added together, euicc, sgp.32, iot esim, remote sim provisioning, sgp.22, sm-dp+ and esim provisioning come to 470 searches a month in the UK.

The diagnostic phrases come to 430, and a single one of them, esim not working, accounts for 320 of that. The failure side of the subject is level with the entire architecture vocabulary combined, and almost all of it sits behind one plain-English query.

The trend is worth noting too. UK interest in sgp.32 has grown from around 40 searches a month in August 2025 to between 110 and 170 through mid-2026, so the architectural story is landing. Meanwhile esim not working has stayed flat and seasonal, peaking in the late-summer travel months at around 390.

Two conclusions follow. The industry is documenting the specification well and the field diagnosis badly. And the people hitting these failure modes are not searching for sm-dp+ when it happens; they are searching in plain language, which means the diagnostic content that would help them is not written in the vocabulary the specification uses.

Why this matters for SGP.32 fleets

The obvious objection is that a consumer retail operation and a managed IoT estate are different problems. They are. But the state-model failure is architectural rather than sectoral, and SGP.32 makes it more likely rather than less.

In SGP.32 the eIM is the orchestration layer: it assigns profiles, coordinates fleet-wide operator changes and applies policy. It is the component that answers "is the estate healthy?". That answer is only as good as the field it reads.

• If a fleet health check tests whether the operational profile was downloaded, it will report as healthy devices that are sitting on a bootstrap profile or on nothing at all. Download and enable are separate operations under SGP.32 exactly as they are under SGP.22.
• A profile switch event is not a connectivity confirmation. It may trigger a modem reset and network re-registration, and re-registration can fail for reasons that have nothing to do with the profile. The switch succeeding and the device being online are two different facts.
• On multi-profile devices, "which profile is enabled" is a question with a real answer that has to be read, not assumed. Only one profile can be active. The one you assigned is not necessarily the one that is running.

A fleet device does not ring support when its profile is installed and disabled. It leaves a gap in a time series that somebody notices later. The consumer case simply surfaces this faster: a retail operation gets an unhappy human within minutes of a state mismatch, while a fleet of environmental sensors in roadside cabinets gets a gap in a time series that somebody notices next quarter, and by then the useful diagnostic window has closed.

Installation is easy to read. Enablement and actual traffic are the ones that tell you whether anything works.

A short checklist

For anyone building on top of a provisioning API, consumer or IoT:

1. Store the vendor's lifecycle status and the enablement status as separate fields. Never derive one from the other.
2. Timestamp every state you cache, and refuse to display it as current beyond a defined age. Stale state produces confidently wrong advice.
3. Treat consumed data as the primary health signal. It is the only field that cannot have registered unless everything else worked at that point in time.
4. Alert on transitions, not on resting states. GOT_RESOURCE is not an incident.
5. Test the full chain end to end, including the delivery mechanism, against a real endpoint you can read back.
6. Document the failure vocabulary in the words your users will use, not the words the specification uses.

None of this is novel engineering. All of it was learned the expensive way, which is the only reason it is worth writing down.