Limited Success Response

[gmuratk]

What type of PR is this?

• enhancement/feature

What this PR does / why we need it:

The current CAMARA API Design Guide does not explicitly define or standardize handling for limited success response cases (informative 2xx responses). These responses represent successful operations with partial fulfillment due to factors such as user preferences or temporary subject unavailability.

As a result, CAMARA APIs currently adopt inconsistent patterns when reporting scenarios like privacy control limitations or subject context restrictions. This inconsistency complicates both client implementation and interoperability across APIs that need to express partial but valid outcomes.

Which issue(s) this PR fixes:

Fixes #555

Does this PR introduce a breaking change?

• Yes
• No

Special notes for reviewers:

Changelog input

 release-note
- Introducing a new section '2.3 Limited Success Responses' to API Design Guide 
- Adding common schema definition SuccessLimitedPayload to CAMARA_common.yaml

Additional documentation

This section can be blank.

docs

[rartych]

I wonder if other code from Successful Response codes can be used to distinguish limited success from ample success response directly on the response level.

Common scenarios for other codes are:

• 202 Accepted: The request was valid and accepted for processing, but isn't complete yet (useful for async operations)
• 206 Partial Content: The request succeeded but only a subset of data is being returned (e.g., due to pagination, filtering, or resource constraints)

For me 202 Accepted looks better, although it is used in CAMARA for asynchronous responses

Using other code than 200 would allow to keep the current definition of 200 response consistent across all APIs.
Any views on that?

[rartych]

I am not sure if section 2.3 is the best place for this guidelines.
We have section 5.7.6. Responses that deals with success responses - maybe it can be extened to describe partial success and include the response pattern in code example?
We need also to place the guidelines related to asynchronous responses as this case is not covered yet - then chapter 3 Error Responses could be reshaped to cover all response types and referenced in 5.7.6.

[gmuratk]

I wonder if other code from Successful Response codes can be used to distinguish limited success from ample success response directly on the response level.

Common scenarios for other codes are:

• 202 Accepted: The request was valid and accepted for processing, but isn't complete yet (useful for async operations)
• 206 Partial Content: The request succeeded but only a subset of data is being returned (e.g., due to pagination, filtering, or resource constraints)

For me 202 Accepted looks better, although it is used in CAMARA for asynchronous responses

Using other code than 200 would allow to keep the current definition of 200 response consistent across all APIs. Any views on that?

@rartych
As you stated 202 - Accepted indicates there is further processing, but LimitedSuccessResponse is intended for cases where there is no further action anticipated.

Status code 206, not sure how widely is used in the CAMARA APIs, but it implies there is more data, but again that's not the intent with the LimitedSuccessResponse.

Also, each API defines its own 200 - responseBody. Introducing an alternative with the 'oneOf' wouldn't be a breaking change and if we agree there is wide applicability, then Design Guide may suggest inclusion of it across the APIs.

[gmuratk]

I am not sure if section 2.3 is the best place for this guidelines. We have section 5.7.6. Responses that deals with success responses - maybe it can be extened to describe partial success and include the response pattern in code example? We need also to place the guidelines related to asynchronous responses as this case is not covered yet - then chapter 3 Error Responses could be reshaped to cover all response types and referenced in 5.7.6.

It was just a suggestion. We can certainly include in a different section as you suggest.

[PedroDiez]

Given the proposal seems to manage scenarios where there is a limitation based on contextual or operational factors (e.g., device unreachable, not processable etc.), I wonder which is the rationale under considering them as success scenarios and not error ones managed by a HTTP 422 code, due to the fact that the request is understood by the server but not proccessable by any means.

In that way, there have been similar scenarios like location-verification where this case is being managed by an error case (e.g. 422 "LOCATION_VERIFICATION.UNABLE_TO_LOCATE")

In that way, we could define a set of transversal error CODE for these kind of scenarios.

At the end of the day I have these doubts:

• Which is the rationale/benefit of managing them as success cases
• In case it is reused 200 OK, that will be a breaking change for subproyects in which this model would be adopted.
• It is somewhow weird to use an error model for a success response
• And a collateral effect of managing as a success case, that would imply that these responses would or could be tarified/charged and not sure whether this would be the better way forward, because an API consumer could argue why it is charged when receiving an answer that is not related at all with the "expected regular" API response associated to an API endpoint.

[gmuratk]

Hi @PedroDiez

RFC 9110 states "The 4xx (Client Error) class of status code indicates that the client seems to have." Therefore, it can equally be misleading to respond with 4xx code in cases like these.

I agree that using the ErrorInfo structure for success case is weird, and at first, I didn't want to use. But in the spirit of leveraging existing structures rather than introducing new one, I chose to suggest this option. We can discuss the most appropriate option.

The reasoning for 'non-breaking change' claim is, proposed approach is semantically backward compatible - it preserves the existing 200 response and behavior while adding an alternative response. That said, this change is expected to be introduced as a minor version change (via release cycle), and that will flag to client the new version has schema change. If it is more appropriate to mark as 'introduces breaking change', I can update the PR template accordingly.

[Kevsy]

I can think of two categories of 'limited success' in API fulfillment: requests that apply to a single resource, and requests to collections.

For a single resource:

• an expectation requested in the operation could not be delivered, but a lower level of expectation could. Examples: location retrieval that can only be sourced at a lower level of accuracy, Quality of Service that is bound to a lower network performance.

For a collection:

• the request could be fulfilled for some of the resources in the collection, and not for others (i.e. 200/201 for some of the resources, 4xx/5xx for others)
• the expectation requested in the operation could be delivered for some resources, but at a lower level of expectation for others

In each case, the request has been received, understood, processed and responded to. Which makes it a 200/201/204 per RFC 7231. But we want the developer to known that their expectation has not been fully met, so we can provide a description in the status and message fields as appropriate.

[rartych]

Some more thougts from my side.
I think we need to clearly define what is "limited success" and what is "failure". The simple way of rating/charging responses can be based on response codes, then 200 "Limited success" response providing only context can be misleading.

• in case described by @Kevsy: expectation requested in the operation could not be delivered, but a lower level of expectation could. Examples: location retrieval that can only be sourced at a lower level of accuracy, Quality of Service that is bound to a lower network performance. - such option should be envisaged in regular API response 200/201/204 - (and possibly in request parameter indicating that lower level of service is acceptable)
• in case the request can not be fulfilled due to factors such as user preferences or temporary subject unavailability as it is not related to client (4xx) should we consider 503 Service Unavailable? - it is also used when service depends on external APIs or services (user preferences, device not connected) and 503 is used for temporary situations, the request can be repeated - then the normal ErrorInfo can be applied:
  • Should 422 "LOCATION_VERIFICATION.UNABLE_TO_LOCATE" be changed to 503 "LOCATION_VERIFICATION.UNABLE_TO_LOCATE" or specific status 503 added for temporary unavailability of location verification result ?
  • And transversal errors like 503 DEVICE_NOT_CONNECTED, etc. could be defined

[PedroDiez]

Regarding scenarios:

• For a single resource: 'an expectation requested in the operation could not be delivered, but a lower level of expectation could'. Think we have already in place solutions like location verification indicating partial response even matchRate or KYC-match (xxxMatchScore concepts), so the best wat would be selected by an inititative.

• For a collection: the rationale of using 422 is based on the fact that it fits well to represent a business condition (we have already used it in other scenarios) and it does neither imply a syntax error from the API consumer nor a server error. As per RFC 9110:

'The 422 (Unprocessable Content) status code indicates that the server understands the content type of the request content (hence a 415 (Unsupported Media Type) status code is inappropriate), and the syntax of the request content is correct, but it was unable to process the contained instructions.'

[patrice-conil]

Regarding scenarios:

• For a single resource: 'an expectation requested in the operation could not be delivered, but a lower level of expectation could'. Think we have already in place solutions like location verification indicating partial response even matchRate or KYC-match (xxxMatchScore concepts), so the best wat would be selected by an inititative.
• For a collection: the rationale of using 422 is based on the fact that it fits well to represent a business condition (we have already used it in other scenarios) and it does neither imply a syntax error from the API consumer nor a server error. As per RFC 9110:

'The 422 (Unprocessable Content) status code indicates that the server understands the content type of the request content (hence a 415 (Unsupported Media Type) status code is inappropriate), and the syntax of the request content is correct, but it was unable to process the contained instructions.'

I share @PedroDiez's point of view.

[rartych]

@PedroDiez Thank you for clarification. I agree that 422 can be used for the case when succesful response can not be delivered due to external conditions.
Summarizing: it looks that for each API it should be decided separately how these edge cases are addressed:

• responding with 200 OK and limited success indicated be specific attribute for example matchRate or one of enum values in the response
• responding with Error (422) when context (like Device not connected) doesn't allow to provide succesful response
• using both methods - like in Location Verification API
• not allowing limited succes response?

Probably we can add a section in chapter 3 Error Responses to have it documented.

[gmuratk]

A couple of points from my side:

Many CAMARA APIs currently handle "edge" cases—where a request is valid but cannot be fully fulfilled—using custom or inconsistent response structures. For example:

• qos-provisioning: ASSIGNMENT_UNAVAILABLE (200 response, but assignment not possible)
• population-density-data: PopulationDensityOperationNotCompletedExample (200 response, but operation not completed)

Adopting a standardized payload for these "limited success" responses would enable predictable client handling, reduce documentation-dependent logic (e.g., statusInfo required when status is OperationNotCompleted), and simplify SDK development.

Regarding the use of 422: In cases like Location_Verification.Unable_to_locate, the request is syntactically and semantically correct, but the operation cannot be fulfilled. According to RFC 9110, 422 is for "unable to process the contained instructions," but here, the issue is not with the request itself. Returning a client error may not be ideal—instead, a 200 response with a standardized limited-success payload would better communicate the outcome to API consumers.

Standardizing these responses would make the APIs more developer-friendly and consistent across the CAMARA ecosystem.

[Kevsy]

HI @gmuratk

where a request is valid but cannot be fully fulfilled

qos-provisioning: ASSIGNMENT_UNAVAILABLE (200 response, but assignment not possible)

population-density-data: PopulationDensityOperationNotCompletedExample (200 response, but operation not completed)

These both look like examples of valid requests which cannot be fulfilled (so 'no success' instead of 'limited success'). Consider instead this example of limited success from population-density-data:

• PART_OF_AREA_NOT_SUPPORTED: Part of the requested area is outside the MNOs coverage area, the cells outside the coverage area will have property dataType with value NO_DATA."

For your second point:

Regarding the use of 422: In cases like Location_Verification.Unable_to_locate, the request is syntactically and semantically correct, but the operation cannot be fulfilled.

I agree: referring to my comment here, this is a service exception. I believe a good way to distinguish between client error and service exception is that a request with a client error will always fail if repeated - which may or may not be the case with a service exception such as Location_Verification.Unable_to_locate . As always, the server can help the client by using the response code/message to help the client decide what to do next (e.g. retry the request, wait for a period and retry, etc.)

[gmuratk]

Thanks @Kevsy,
I listed the Assignment_Unavailable and OperationNotCompleted examples since both are listed as 200 Success messages. May be the label 'SuccessLimitedPayload' is too restrictive and can be changed to "LimitedOrNoSuccessPayload" to be appropriate for 'no success' 200 responses.

I wanted to show precedence in the APIs that there are cases where limited or no success cases are responded with 200 status, and it will be best if we can define a standard structure to communicate limited or no success cases, without taking away the option for providers to respond with a 'service exception' as it is done today.

[Kevsy]

Thanks @gmuratk , understood.

The use of HTTP status codes to indicate API success (or not) is tricky because HTTP completion is not the same as API fulfillment. Especially the scope of the word 'success': as the RFC says, "The 200 (OK) status code indicates that the request has succeeded", but 'request' in that sentence simply means the HTTP request - not the API request.

I wanted to show precedence in the APIs that there are cases where limited or no success cases are responded with 200 status, and it will be best if we can define a standard structure to communicate limited or no success cases, without taking away the option for providers to respond with a 'service exception' as it is done today.

Yes, I think that's important.

[eric-murray]

This example is out of date, as the roaming API now returns a lastStatusTime field indicating when the roaming status was last confirmed correct. So even if the device is currently not connected to a mobile network, a historical status can still be returned.

If the API provider genuinely has no idea as to the roaming status (maybe they don't maintain any history for the device), then the agreed error is 503. This scenario is not even a partial success.

So an alternative example is required. Or the example should be removed.

[gmuratk]

Obsoleted by #567