eSIM RSP Knowledge Base

Comprehensive technical knowledge base covering 12 GSMA eSIM specifications. 84+ articles on Remote SIM Provisioning — SGP.02, SGP.22, SGP.32, SGP.41, SGP.29, SGP.23, SGP.25, SGP.26 and more.

Project maintained by AlexsCodingAgent Hosted on GitHub Pages — Theme by mattgraham

Notifications and Error Handling in IoT eSIM

🏠 eUICC.tech > SGP.32 IoT eSIM > Notifications and Error Handling in IoT eSIM

💡 Why this matters: When a profile changes state on an IoT device deployed in a remote location: enabled, disabled, deleted, or failed: someone needs to know. SGP.32 defines a structured notification system and three-level error architecture purpose-built for the asynchronous, occasionally-connected world of IoT. Understanding this system is essential for anyone building an eIM or integrating with one.

Key takeaways:

Notifications are generated by the eUICC on every profile state transition and propagate to SM-DP+ and eIM

Notifications can be bundled with eUICC Package Results to minimise airtime on constrained links

Three-level error architecture: IPA errors (pre-eUICC), eUICC Package errors (unsigned/signed), PSMO/eCO execution errors

Profile Rollback provides recovery when the IPA loses connectivity after executing a PSMO

Emergency Profile preemption blocks ALL eSIM operations during eCall (ecallActive(104))

When a profile state changes on an IoT device deployed in a remote location, someone needs to know. SGP.32 defines a structured notification system and comprehensive error handling for the asynchronous, occasionally-connected world of IoT.

The Notification System

Notifications are generated by the eUICC whenever a profile transitions state. They propagate through the IPA to Notification Receivers : typically the SM-DP+ and the eIM.

What Triggers a Notification

Event	Notification Type
Profile enabled	`enableNotification`
Profile disabled	`disableNotification`
Profile deleted	`deleteNotification`
Profile installed	`installNotification`
Profile download error	`errorNotification`

Each profile’s metadata includes notificationConfigurationInfo : which events generate notifications and where they should be sent.

Notification Delivery Flow

1. eUICC generates notification → stored as PendingNotification

2. IPA retrieves pending notifications:
   IPA → eUICC: ES10b.ListNotification
   IPA → eUICC: ES10b.RetrieveNotificationsList

3. IPA delivers notifications to receivers:
   IPA → SM-DP+:   ES9+.HandleNotification
   IPA → eIM:      ESipa.HandleNotification

4. Receiver acknowledges → IPA deletes from eUICC:
   IPA → eUICC: ES10b.RemoveNotificationFromList(sequenceNumber)

Combining Notifications with eUICC Package Results

To minimise airtime on constrained links, the IPA can bundle notifications with eUICC Package Results:

IPA → eIM: ESipa.ProvideEimPackageResult
    Contains:
        - Signed euiccPackageResult    (from PSMO/eCO execution)
        - PendingNotificationList      (from recent profile state changes)

The eIM processes both in one round trip, acknowledges them together, and the IPA removes them from the eUICC in a single cleanup pass.

Compact Notification Format

For IPAs with minimizeEsipaBytes capability, notifications can use abbreviated encoding: stripping redundant fields that the eIM can reconstruct from its own state database. The eIM expands compact notifications back to full format before forwarding to other Notification Receivers.

`IPAe` Notification Handling

When the IPA lives in the eUICC (IPAe), the IPAe retrieves notifications directly from ISD-R, packages them, and either:

Triggers an eIM Package Retrieval (IPAe-initiated pull via eimRetrieveHttps or eimRetrieveCoaps)
Waits for eIM Package Injection (eIM-initiated push via eimInjectHttps or eimInjectCoaps)

The choice depends on the device’s connectivity pattern: polling devices use injection, sleeping devices use retrieval on wake.

Error Handling Architecture

SGP.32 defines error handling at three levels:

Level 1: IPA Errors

Errors detected by the IPA before messages reach the eUICC:

Error Code	Meaning
`incorrectTagList`	ASN.1 parsing failed: invalid eIM Package structure
`euiccCiPKIdNotFound`	eIM requested a CI key the eUICC doesn’t have
`ecallActive`	Emergency call in progress: all eSIM ops blocked

The IPA returns IpaEuiccDataResponseError (for data requests) or ProfileDownloadTriggerResult with error (for download triggers).

Level 2: eUICC Package Errors

Errors detected by the eUICC during eUICC Package processing:

EuiccPackageError ::= CHOICE {
    euiccPackageErrorUnsigned    EuiccPackageErrorUnsigned,
    euiccPackageErrorSigned      EuiccPackageErrorSigned
}

EuiccPackageErrorUnsigned ::= SEQUENCE {
    eimTransactionId  [0] TransactionId OPTIONAL,
    euiccPackageErrorReason INTEGER {
        counterTooLow(1),
        eimSignError(2),
        ecallActive(104),
        undefinedError(127)
    }
}

Unsigned errors occur before the eUICC verifies the eIM’s signature (counter too low, malformed package).

Signed errors occur after signature verification (profile not found, policy rule violation, insufficient memory). These are signed by the eUICC to prove the error came from the genuine chip.

Level 3: PSMO/eCO Execution Errors

Individual operations within a package can fail independently:

Operation	Error Codes
EnableProfile	`iccidOrAidNotFound`, `profileNotInDisabledState`, `pprNotAllowed`, `disablingNotAllowed`
DisableProfile	`iccidOrAidNotFound`, `profileNotInEnabledState`, `pprNotAllowed`
DeleteProfile	`iccidOrAidNotFound`, `profileNotInDisabledState`, `pprNotAllowed`
RollbackProfile	`undefinedError`
SetFallbackAttribute	`iccidOrAidNotFound`, `fallbackNotAllowed`, `fallbackProfileEnabled`
UnsetFallbackAttribute	`noFallbackAttribute`, `fallbackProfileEnabled`
addEim	`insufficientMemory`, `associatedEimAlreadyExists`, `ciPKUnknown`, `invalidAssociationToken`
deleteEim	`eimNotFound`
updateEim	`eimNotFound`, `ciPKUnknown`, `counterValueOutOfRange`

Error Recovery Patterns

Profile Rollback: If the IPA fails to deliver an eUICC Package Result to the eIM (connectivity loss after executing a PSMO), the IPA calls ES10b.ProfileRollback : reverting the eUICC to the previously enabled profile state. The eUICC automatically discards the undelivered result and generates a new one reflecting the rollback.

Unreachable ESP Pattern: If the eIM sends a package and the device never acknowledges (extended PSM sleep), the eIM must handle timeout internally: SGP.32 doesn’t mandate a specific retry policy, leaving it to eIM implementation.

Emergency Profile Preemption: When the Emergency Profile is enabled (eCall in progress), the eUICC rejects ALL eUICC Packages, Profile Downloads, and IpaEuiccData requests with ecallActive(104). Profile operations during an emergency call could drop the connection: unacceptable for safety-critical systems.

📋 Summary

Structured notifications propagate from eUICC → IPA → eIM/SM-DP+ on every profile state transition
Bundling notifications with eUICC Package Results saves airtime on constrained links
Three error levels (IPA, eUICC Package, PSMO/eCO execution) provide granular failure diagnostics
Profile Rollback and Emergency Profile preemption handle the two most critical IoT failure modes

← Previous: eIM Configuration: Associating Remote Managers with Your eUICC · 🏠 Home Next: IoT Device Initialisation and the eUICC File Structure →

Based on GSMA SGP.32 v1.3, Sections 3.6-3.7

← Previous: eIM Configuration: Associating Remote Managers with Your eUICC

Section Index

Next: IoT Device Initialisation and the eUICC File Structure →