Discussion: 409 ALREADY_EXISTS Error Code for Subscription Consistency

[ravindrapalaskar17]

Currently, different subscription APIs handle duplicate subscriptions inconsistently when a subscription is created using phoneNumber.

For example:

SIM Swap Subscription and Device Location (Geofencing) allow multiple subscriptions for the same phone number.

Device Status Subscription throws a 409 ALREADY_EXISTS error, but it considers both phoneNumber and type before determining duplication.

Discussion Points:
Should we enforce a common rule for all subscription APIs?

Option 1: Throw a 409 ALREADY_EXISTS error when a subscription is created with the same phoneNumber.

Option 2: Allow multiple subscriptions for the same phoneNumber, but only when a valid use case and reason are provided.

What should be the criteria for determining a duplicate subscription?

Should it be based only on phoneNumber?

Should we consider additional parameters (e.g., subscriptionType, reason)?

How should we handle exceptions consistently across all subscription APIs?

If we decide to allow multiple subscriptions, should we add a standard mechanism to validate the use case before permitting them?

The goal is to finalize a consistent approach for handling duplicate subscriptions across all APIs, ensuring alignment and clarity. Looking forward to your inputs!

[PedroDiez]

From our view, it will be needed to check below points for the 409 ALREADY_EXISTS criteria (that is the way we do):

2-legged mode

• API Client (Developer App, identified by their credentials)
• Event type (types field in request)
• phoneNumber (config.subscriptionDetail.phoneNumber)

3-legged mode

• API subject (Identified by means of Access Token) (*)
• API Client (Developer App, identified by their credentials)
• Event type (types field in request)
• phoneNumber (config.subscriptionDetail.phoneNumber)

(*)
In Fall24 it has to match to config.subscriptionDetail.phoneNumber -> otherwise 403 - INVALID_TOKEN_CONTEXT
In Spring25 phoneNumber must not be indicated -> otherwise 422 UNNECESSARY_IDENTIFIER

[sachinvodafone]

Thanks @ravindrapalaskar17 for bringing this topic into the discussion. In the context of geofencing, there are valid scenarios where duplicate subscriptions for the same phone number, event type, and area might be required.
Example Scenario:
A single truck arrival event might need to notify multiple independent systems:

• Warehouse staff – to begin physical preparations
• Logistics software – to update internal systems
• Fleet manager – to trigger a dashboard alert

To achieve this, clients may create multiple subscriptions that are identical in all fields except the sink URL:

Subscription 1:
phoneNumber: "+123456789"
type: "area-entered"
area: { center: [lat1, lon1], radius: 1000 }
sink: "https://warehouseA.example.com/notify"

Subscription 2:
sink: "https://logistics.example.com/notify"

Subscription 3:
sink: "https://manager.example.com/notify"

Each subscription exists to serve a distinct stakeholder with different processing needs. In this case, allowing duplicates is reasonable and aligned with real-world multi-party use cases.

Horeover, if the sink URL is also identical (e.g., all use https://warehouseA.example.com/notify), it becomes a clear case of redundancy. In such instances, we can reject exact duplicates—those matching on phoneNumber, type, area, and sink—with a 409 ALREADY_EXISTS error, aligning with the stricter approach of the "Device Status Subscription" API.

So I will go with Option 2, where the potential use cases allowing such scenarios are clearly documented to avoid confusion.

[ravindrapalaskar17]

Thanks @sachinvodafone a lot for the detailed and practical feedback!

Your example around the geofencing use case is a great demonstration of why allowing multiple subscriptions for the same phone number can be valid — especially when different sinks are involved for distinct business stakeholders. That really helps clarify the reasoning behind permitting such "duplicate" subscriptions under controlled and justifiable conditions.

I completely agree that in scenarios where the only differing parameter is the sink URL, and the subscriptions serve independent systems or users, allowing multiple subscriptions makes sense and supports real-world needs. At the same time, enforcing a 409 ALREADY_EXISTS response for exact duplicates (i.e., matching on phoneNumber, type, area, and sink) provides the right balance by avoiding redundancy.

If we decide to go with option number 2 then we need to ensure:

• Clear documentation of valid multi-subscription scenarios.
• A consistent duplicate-check logic across APIs (e.g., based on a composite key of phoneNumber + type + area + sink).
• Standardized exception handling (409 with a clear message) for true duplicates.

[PedroDiez]

Good point @sachinvodafone to comment about use cases that also consider sink in the logic for redundancy subscriptions.
cc @jlurien, @jgarciahospital