KYC-Match: Error responses alignment with Commonalities

[rartych]

What type of PR is this?

Add one of the following kinds:

• correction

What this PR does / why we need it:

Alignment with API Design Guidelines on Error Responses
https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#62-error-responses---device-object

Added description based on Annex A https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#appendix-a-infodescription-template-for-device-identification-from-access-token
but limited to Phone Number .

Which issue(s) this PR fixes:

Fixes #

Special notes for reviewers:

For Error 422 changes are based on
https://github.com/camaraproject/CallForwardingSignal/blob/main/code/API_definitions/Call_Forwarding_Signal.yaml

Changelog input

Correction for error responses

Additional documentation

[jgarciahospital]

HI @rartych we prefer to wait for commonalities alignment (spring25) to include this new error.

Up to now, this situation can be handled as it is: HTTP 403 INVALID_TOKEN_CONTEXT in case 3 legged is used and numbers don't match, and 400 Invalid argument in case phone-number is both missed in token (2-legged) and also no present in API request body.

[rartych]

Let's postpone the decision to Spring25 meta-release then.

[ToshiWakayama-KDDI]

Hi @jgarciahospital , @rartych ,

From KDDI side, we would agree with your views that this proposal PR #115 should be postponed.

Since KYC Match has 'phoneNumber' as an optional parameter, I think we should keep it. Let's discuss further.

Best regards,
Toshi
KDDI

[fernandopradocabrillo]

@ToshiWakayama-KDDI @rartych
A couple of corrections based in the agreements for other WGs and Commonalities.

• 422_NOT_SUPPORTED -> when the service is not supported for the provided phone number (e.g. a B2B phone number). Reference: Added 501 Not Supported error response Commonalities#145 (comment)
• UNIDENTIFIABLE_PHONE_NUMBER -> when the phone number is not provided in the request body a cannot be deducted from the access token. The UNIDENTIFIABLE_DEVICE should be used only when the API uses the object device. Reference Extracting phoneNumber from the 3-legg access token SimSwap#117

[rartych]

@fernandopradocabrillo Currently there are no explicit Commonalities guidelines on error responses related to phoneNumber only used for identification. This should be resolved in the next Commonalities release, this PR will be updated then to be fully aligned.

[fernandopradocabrillo]

@fernandopradocabrillo Currently there are no explicit Commonalities guidelines on error responses related to phoneNumber only used for identification. This should be resolved in the next Commonalities release, this PR will be updated then to be fully aligned.

@rartych sorry I didn't get that, to what error are you refering exactly, the UNIDENTIFIABLE_PHONE_NUMBER?

[ToshiWakayama-KDDI]

Thank you, @fernandopradocabrillo , @rartych.

From KDDI side, we would postpone these proposals if they are not MUST to aligne with Commonalities v0.4, as we have decided to postpone.

And, also, since KYC Match has 'phoneNumber' as an optional parameter, we should keep it from the backward compatibility point of view.

Best,
Toshi

[rartych]

From DT side we do not have preference.
This PR can be postponed as the API is in version 0.2 - subject to significant changes before 1.0

[fernandopradocabrillo]

Hi @ToshiWakayama-KDDI
Just to sum up this issue and give you our thoughts. The error in discussion wants to cover the scenario where the token cannot be deducted from the access token and it hasn't been provided in the request body

There has been a major rework in Commonalities regarding this topic, but it has been focalized for APIs that use the "device" object, which includes the phone number as a possible identifier.

The decission in commonalities v0.4 has been to use a dedicated error, the 422 UNIDENTIFIABLE_DEVICE. When the WGs started to spread this new error across all APIs, we realized that those APIs that use only the phone number as input faced the exact same problem as the ones that use the "device" as input.

The initial proposal for KYC v0.2.0 from @rartych to align the API with commonalities v0.4, included the already approved error: UNIDENTIFIABLE_DEVICE. But, in other WGs like Sim Swap and Number Verification, there was a discussion involving several operators on how to tackle this error since the approved one can only be used for APIs that managed the concept of the "device" object. So, the conclusion was to create a new specific error UNIDENTIFIABLE_PHONE_NUMBER that is, essentially, the same error but adapted to APIs that use only the phone number as input. That decission is based in the Commonalities guidelines that allows the WG to define 422 specific errors if they need them. Therefore Telefonica proposal has been to use this last error, not yet approved in commonalities but already proposed in other APIs.

The updated description in "info.description" describes al the error scenarios in detail and how the API should behave. This text is the same one that exists in Commonalities for the device object, but adapted for the phone number.

We strongly believe we should include it and align with other WGs, it makes the API more clear and robust and, it is not a really big.

[ToshiWakayama-KDDI]

Thanks, @fernandopradocabrillo , for your comments.

What you mentioned gerenally makes sense. However, from KDDI side, actually we are using phoneNumber as an optional parameter, which is to be checked, as our customers (API users) want to know if phoneNumber is correct, as part of KYC Match, for example, when it is provided by the end user. As you know, KYC Match user story includes phone number to be checked.
So, maybe a bit different from SIM Swap use cases, as well as from your perspective. So, we need phoneNumber, an opitional parameter, and that is what I mentioned before as backward compatibility.

So, we think we need some more time to discuss how to write this content in the KYC Match desciription, and I proposed to postpone. But, if you insist on including it, our point is the part 'therefore it is recommended NOT to include it in these scenarios to simplify the API usage and avoid additional validations', which we feel is strong. So, for example, could you remove this part? Because other parts, e.g. validation mechanism and error 403/422, make sense.

Best regards,
Toshi

[fernandopradocabrillo]

Hi @ToshiWakayama-KDDI,
The proposed text is actually just an adaptation from the already approved one in Commonalities link.

I understand your concern and I don't plan to push the topic any further and affect the release. But it is something we'll have to discuss and probably end up including since it is very related to the API missuse issue.

[ToshiWakayama-KDDI]

Thank you @fernandopradocabrillo for your understanding. Yes, I understand we'll have to discuss this after the Meta-release rush, and I will follow the API misuse discussion.

Many thanks,
Toshi

[fernandopradocabrillo]

Hi @ToshiWakayama-KDDI ! just FYI, the text proposed and the error are now included in commonalities pre-release v0.4.0-rc2 for the Fall24 meta.

[GillesInnov35]

hello all, do we agree we could follow Commonalities guidelines https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#62-error-responses---device-object and add the ERROR 422 in kyc error management as it has been done in API (QoD for example).
Thanks
BR
Gilles

[ToshiWakayama-KDDI]

Thanks, Gilles, for reminding that this PR #115 discussion is open.

From KDDI side, we would prefer to keep 'phoneNumber' optional and usable for various use cases potentially, even when 3-legged access token is used. Actually we are providing this API to some customers in such a way.

Let's discuss further for a way forward which is suitable for us.

I will check the misuse discussion in Commonalities.

Best regards,
Toshi

[GillesInnov35]

Thanks @ToshiWakayama-KDDI

[GillesInnov35]

hi all, according to what has been validated and supported by Eric Murray for Tenure API camaraproject/Tenure#11, do you think we all could validate and update kyc-fill-in and kyc-match's errors section in order to be consistent. What do you think about that ?

Thanks a lot
BR
Gilles

[GillesInnov35]

Thanks

[ToshiWakayama-KDDI]

Thanks, @GillesInnov35 . I need some more time to check what has been discussed and validated for Tenure API. I also think we need to check Commonalities discussion. At least, from Commonalities discussion, I feel we do not have to be consistent among APIs, because each API has different scope, even in the KYC family.

Best regards,
Toshi

[rartych]

For Spring25 Commonalities WG is preparing significant changes in error responses:

• Enhancements and Alignments in Errors Commonalities#329
• Update error codes and info.description template for device / phone number identifiers Commonalities#324
• Normalization of error status and code allowed values Commonalities#316

This PR does not conform to the proposed guidelines.
It can be updated or closed (and replaced with new the PR) when release candidate of Commonalities is published (expected mid of December).