Duplication of error code semantics, i.e. CONFLICT and ALREADY_EXISTS

[tlohmar]

Problem description

CAMARA commonalities includes two error codes within the 409 CONFLICT HTTP status code, which are semantically identical.

The error code CONFLICT has the same meaning as the error code ALREADY_EXISTS. Both address the error condition, that an API operation cannot be executed it leads to a duplication of an existing resource.

Expected behavior

Remove or disallow the usage of one of the two error codes. Preferably keep ALREADY_EXISTS, since clearer for an API developer and more to the point.

Alternative solution

Additional context

[Kevsy]

Preferably keep ALREADY_EXISTS, since clearer for an API developer and more to the point.

+1

[PedroDiez]

I would keep CONFLICT. Get your point in the PR#550 Thomar. Was just refering to a naming in RFC.

Anyway, fine to do the simplification and OK if it is seen better to keep ALREADY_EXISTS

[Kevsy]

I would keep CONFLICT. Get your point in the PR#550 Thomar. Was just refering to a naming in RFC.

The problem is that CAMARA Commonalities has redefined 'CONFLICT' to a different meaning than RFC 7231 Conflict.:

The 409 (Conflict) status code indicates that the request could not
be completed due to a conflict with the current state of the target
resource. This code is used in situations where the user might be
able to resolve the conflict and resubmit the request.

...but Common.yaml restricts CONFLICT to " A specified resource duplicate entry found.". Duplication is one example where "the request could not be completed due to a conflict with the current state of the target resource" but not the only one. The RFC goes on to give the most likely cause:

Conflicts are most likely to occur in response to a PUT request. For
example, if versioning were being used and the representation being
PUT included changes to a resource that conflict with those made by
an earlier (third-party) request, the origin server might use a 409
response to indicate that it can't complete the request.

So to avoid conflict with the existing definition of Conflict (🥁 ) it makes sense to use ALREADY_EXISTS for the specific case of duplication, and add other specific cases as required (e.g. INCOMPATIBLE_STATE).

[tlohmar]

Seems that there is convergence. Followup question: Should we remove the Error code from common.yaml or should we disallow the usage of the obsolete error code in the API Guideline (and maybe also the descriptive text of common.yaml)?

[rartych]

The current definitions are as follows:

             GENERIC_409_ALREADY_EXISTS:
                 code: ALREADY_EXISTS
                 message: The resource that a client tried to create already exists.
                 status: 409
            GENERIC_409_CONFLICT:
                 code: CONFLICT
                 message: A specified resource duplicate entry found.
                 status: 409

ALREADY_EXISTS for me is related to creating very similar resource second time, while CONFLICT just indicates duplication of some entry.

The results of the automated analysis of Error 409 in current CAMARA APIs can be found here
And the summary looks like that:

APIs with ALREADY_EXISTS (12 total)

1. Blockchain Public Address
2. Carrier Billing
3. Carrier Billing Refund
4. Connected Network Type Subscriptions
5. Connectivity Insights Subscriptions
6. Device Data Volume Subscriptions
7. Device Reachability Status Subscriptions
8. Device Roaming Status Subscriptions
9. Notification Subscription Template
10. Sim Swap Subscriptions
11. Traffic Influence ✓ (also has CONFLICT)
12. WebRTC Events

APIs with CONFLICT (7 total)

1. Brand Registration
2. QoS Booking
3. QoS Booking and Assignment
4. QoS Provisioning
5. Quality-On-Demand
6. Traffic Influence ✓ (also has ALREADY_EXISTS)
7. Verified Caller

Only Traffic Influence lists both values,
CONFLICT is used by QoD APIs to indicate an existing session for the same device, etc. and by VerifiedCaller/Brand - conflicts with existing data in the service platform

[Kevsy]

Thanks for the lists @rartych 👍

ALREADY_EXISTS for me is related to creating very similar resource second time, while CONFLICT just indicates duplication of some entry.

I don't think ALREADY_EXISTS applies unless the resource properties of the request and an existing resource are identical (apart from any primary key resource identifier issued after creation) . But 'very similar' is not the same as 'identical'. So the risk is that that a requested new resource that is slightly different from an existing resource could be incorrectly considered as an error.

while CONFLICT just indicates duplication of some entry.

If 'entry' here applies to the whole resource, then that is the same as 'ALREADY_EXISTS'. Or if 'entry' means 'a duplicate object in the request itself' (e.g. same object listed twice) then that is a 400 Bad request. Or does 'entry' refer to something else...?

[hdamker]

Please don't "remove" any error code if there is not an important reason (e.g. a security issue).

If we want to consolidate error codes which were added by different APIs over time we can do a comprehensive review of how they are used currently and then potentially add guidance when to use which error code for a HTTP status and potentially "deprecate" an error code in Commonalities (which means that a new initial (0.x) or major CAMARA API version shouldn't use this error code any longer) -- which won't imply a breaking change to existing stable versions.

[hdamker]

Situation within quality-on-demand:

• we use generic CONFLICT if there is already a (conflicting) QoD session for a device - that is actually a specific case and would be worth an API specific error code -- or maybe the new "INCOMPATIBLE_STATE" fits, if we consider the device as a "referenced resource"
• In another case (extend session) we are using 409 as intended in the standard: the session must be in state "AVAILABLE" for this operation, otherwise we throw a 409. Here we have defined API specific QUALITY_ON_DEMAND.SESSION_EXTENSION_NOT_ALLOWED ... while a simple CONFLICT with the right message would have been enough

In any way ... the changes don't seem important enough to me to justify a breaking change, so I would always recommend to postpone it to the next major version.

[tlohmar]

Thanks for the lists @rartych. Very helpful. We need to check, how different APIs are using these Error Codes, as suggested by @hdamker.

ALREADY_EXISTS for me is related to creating very similar resource second time, while CONFLICT just indicates duplication of some entry.

When we want to have a consistent usage of these Error Codes across multiple APIs, we need to have clearer definition of "how does the server determine similarity?". APIs may always use a 400 Bad Request with an API specific error code.

[hdamker]

We need to check, how different APIs are using these Error Codes, as suggested by @hdamker.

After some deeper analysis (409-consolidation-recommendation.md), I support deprecating CONFLICT in favor of ALREADY_EXISTS for duplicate resources. The semantic overlap causes developer confusion, and CONFLICT is quite generic.

Within the attachment you find an analysis of the 409 usage across 33 endpoints (18 APIs using standard enum pattern). As this was generated, it might not be consistent in all points, but I challenged the key points in multiple refinements.

Key issues:

1. Semantic overlap: CONFLICT and ALREADY_EXISTS both used for "duplicate resource"
2. Unnecessary API-specific codes: State-checking codes (PAYMENT_CONFIRMED, SESSION_EXTENSION_NOT_ALLOWED) should use generic code
3. INCOMPATIBLE_STATE confirmed as needed: The proposed error code (PR New 409 error code called INCOMPATIBLE_STATE #550) addresses multiple use cases currently handled by API-specific codes
4. Redundant codes: DENIED_WAIT and INCOMPATIBLE_STATE have identical semantics

Proposal: Consolidate to 3 generic codes:

1. ALREADY_EXISTS - Duplicate resource (identical identifying characteristics)
2. ABORTED - Concurrent operations conflict
3. INCOMPATIBLE_STATE - Resource in incompatible state (target or referenced)

Note: Deviating from PR #550 my proposal is to use INCOMPATIBLE_STATE for BOTH target and referenced resource state conflicts:

• Target resource: The resource being operated on (e.g., session being extended)
• Referenced resource: A resource referenced in the operation (e.g., booking not in right state to assign a device)
• The distinction is too subtle for practical API development
• Message field clarifies which resource has the state issue

Deprecate:

• CONFLICT → Migrate to ALREADY_EXISTS (if duplicate) or INCOMPATIBLE_STATE (if state conflict)
• DENIED_WAIT → Migrate to INCOMPATIBLE_STATE
• API-specific state codes → Migrate to INCOMPATIBLE_STATE

Migration should happen in next major API versions (or next initial API versions), not necessarily breaking stable API versions just for this consolidation.