[Masa8106]

What type of PR is this?

• correction

What this PR does / why we need it:

To refer common error response from Commonalities r4.4 as much as possible.

What this PR proposes to refer is:

• 400 Invalid Argument example
• 401 Error response
• 403 Error response

Note that there are error response differences between existing this API specification and r4.4 common.yaml regarding the other error responses.

Which issue(s) this PR fixes:

None

Special notes for reviewers:

Related to #126

Changelog input

 release-note
  -refer common error response from Commonalities r4.4.

Additional documentation

None

[albertoramosmonagas]

See comments and also the PR description includes Fixes #126, but issue #126 (template notice P-027, additional-error-responses) is closed by PR #127, not this one. If merged with Fixes #126, GitHub will automatically close that issue incorrectly. Please remove that line from the description.

[albertoramosmonagas]

Commonalities r4.4 already provides BadRequestWithRange400, IdentifierNotFound404, and PhoneNumberIdentifier422 in CAMARA_common.yaml, with the same schema as these local definitions. Analogous r4.4 APIs that also operate on phone number with /check (SimSwap, DeviceSwap) reference all 5 error codes directly from common, with no local definitions.

Would it be possible to reference 400, 404, and 422 from common and remove the local definitions? A local definition is only needed if Number Recycling has error codes that are specific to this API. The r4.4 precedent for a justified local definition is RetrieveLocationUnprocessableEntity422 in DeviceLocation, which is API-specific.

[Masa8106]

HI @albertoramosmonagas, thank you for your coment.
I can discuss openly on possibility to refer 400, 404, and 422 from common.yaml.
As you pointed out, Number Recycling has same error codes as common.yaml. However, I found that it has different descriptione and/or messagee in 400, 404, and 422 error. So I keep the original description and/or message as local definition at this moment.
So far, I would like to hear opinions also from other code owners. What do you think, @eric-murray and @grgpapadopoulos ?

[Masa8106]

@albertoramosmonagas, it is ok for me to refer common 404 and 422 response. I will update "File changed" in this PR. Regading the 400 response, I am happy if we can keep the local definition as I commented here.

[albertoramosmonagas]

Thanks, referencing 404 and 422 from common looks good. The 400 can stay local as discussed above, provided it follows the r4.4 naming pattern.

[albertoramosmonagas]

The inline OutOfRange example is identical to GENERIC_400_OUT_OF_RANGE from common. If the suggestion above (point 3) is applied and 400 is referenced from common, this is implicitly resolved. If the local definition is kept, this example should be replaced with a $ref to the common example to avoid duplication.

[Masa8106]

Regarding OUT_OF_RANGE, I updated the description by PR #122 after I opened this PR. Now the description is differenct from one specified in the common example, is not duplicated. And the update by PR #122 intends to clarify tihs error. I would like to keep it (not to refer common example).

[albertoramosmonagas]

Thanks for the context. The canonical approach would be to use the common BadRequestWithRange400 response. We understand your point about PR #122 and its specific, non-normative message, and we're fine with whatever the other codeowners prefer.

Keeping the local definition is acceptable, but note that the Release Management review may raise this again. If the local definition stays, please align its naming with r4.4 (see my comment on the response name) and rebase the branch, as the diff still shows the pre-#122 OutOfRange description.

[albertoramosmonagas]

Naming alignment with r4.4: other APIs name local 400 responses BadRequest400 (for example RetrieveConnectivityBadRequest400, CreateSessionBadRequest400), and the example keys follow GENERIC_400_* / 400* as in artifacts/api-templates. Here they are CheckNumberRecycling400, InvalidArgument and OutOfRange. Suggested: CheckNumberRecyclingBadRequest400, with the examples keyed accordingly (GENERIC_400_INVALID_ARGUMENT for the common one, and an 400* key for the local out-of-range example).

[Masa8106]

Thank you for your comment. I tried to rename as you commented. Please check it.

[albertoramosmonagas]

This PR aligns the API definition but not the test definitions (code/Test_definitions/number-recycling.feature), for example the C02 phone-number scenarios. PR #130 covers part of this. Please coordinate both PRs so they land consistently.

And also, the PR description includes Fixes #126, but that issue was already closed by PR #127. Please remove that line so merging does not close it again. If this PR is meant to track the test alignment, please link it with a plain reference (for example “Related to #126”) instead.

[grgpapadopoulos]

Thanks @Masa8106 and @albertoramosmonagas
I support the compromise: reuse the common 404/422 responses while keeping 400 to preserve the clarification from #122 . Let's also ensure alignment with #130

[albertoramosmonagas]

The file must end with exactly one newline after the last line (Y-011). A suggestion cannot express this reliably, so please add the newline in your editor (no extra blank line at the end).

[Masa8106]

@albertoramosmonagas, thank you for suggesting corrections. I have done them.
@grgpapadopoulos, @eric-murray, would you review this PR? Thank you.

[albertoramosmonagas]

Thanks @Masa8106. I see on the linter another warning to solve:

Emit annotations: code/API_definitions/number-recycling.yaml#L1
[P-029] info.description has a BEGIN marker for template 'authorization-and-authentication' without a matching END marker. | info.description has a BEGIN marker for template 'request-body-strictness' without a matching END marker.