Update error response schema for compliance with Commonalities

[eric-murray]

What type of PR is this?

• correction

What this PR does / why we need it:

This PR:

• updates the error response schema and examples for compliance with Commonalities CAMARA_common.yaml
• Replaces NOT_FOUND error code with IDENTIFIER_NOT_FOUND
• Replaces DEVICE_NOT_APPLICABLE error code with SERVICE_NOT_APPLICABLE
• Adds Generic429, Generic502 and Generic504 error codes

Which issue(s) this PR fixes:

Fixes # N/A

Special notes for reviewers:

None

Changelog input

 release-note
 - Update error response schema for compliance with Commonalities

Additional documentation

None

[yamamoto0104]

Hello @eric-murray

Thank you for your proposal. We are reviewing the error codes internally and feedback later. I have a following question.
Commonalities CAMARA_common.yaml shows 404 NOT_FOUND and 404_IDENTIFIER_NOT_FOUND separately. Do we need to replace NOT_FOUND error code with IDENTIFIER_NOT_FOUND?

examples:
           GENERIC_404_NOT_FOUND:
             description: Resource is not found
             value:
               status: 404
               code: NOT_FOUND
               message: The specified resource is not found.
           GENERIC_404_IDENTIFIER_NOT_FOUND:
             description: Some identifier cannot be matched to a device
             value:
               status: 404
               code: IDENTIFIER_NOT_FOUND
               message: Device identifier not found.

[eric-murray]

@yamamoto0104

IDENTIFIER_NOT_FOUND is the error code to return if the phoneNumber is valid but not used by the API provider. See here.

NOT_FOUND is a general 404 error code when "other" objects are not found. But this API does not require references to any other objects to be provided by the API consumer, so we have no need to use that code.

[yamamoto0104]

@eric-murray

I cannot find following description in your provided link.

IDENTIFIER_NOT_FOUND is the error code to return if the phoneNumber is valid but not used by the API provider. See here.

The phone number is valid for an end user, however API provider cannot use the phone number due to operator's policy. Is my understanding correct?

[eric-murray]

The description for IDENTIFIER_NOT_FOUND is:

Some identifier cannot be matched to a device

where you need to interpret "identifier" as "phone number" and "device" as "account" for this API.

So this is the error returned when the phone number is valid, but is not allocated to any of the API provider's customers or in the pool of numbers which could be allocated to customers. In other words, when the phone number actually belongs to a different network operator.

If the phone number is used by the API provider but the service does not apply (e.g. if a fixed line phone number is provided but the service is for mobile numbers only), then the error is 422 SERVICE_NOT_APPLICABLE.

[yamamoto0104]

Suggested change

	allOf:
	- $ref: "#/components/schemas/ErrorInfo"
	- type: object
	properties:
	status:
	enum:
	- 404
	code:
	enum:
	- IDENTIFIER_NOT_FOUND
	examples:
	GENERIC_404_IDENTIFIER_NOT_FOUND:
	description: Provided phone number is not one used by network operator
	value:
	status: 404
	code: IDENTIFIER_NOT_FOUND
	message: Phone number not found.

[yamamoto0104]

404 IDENTIFIER_NOT_FOUND is not applicable to this API. In this case, the API returns true in phoneNumChanged parameter.

[eric-murray]

That's not the purpose of this error. The error is used when, due to a routing error, Operator A receives a number recycling request for a MSISDN that is actually used by Operator B. That's a clear error, because Operator A can say nothing about the MSISDN, so they return a 404 IDENTIFIER_NOT_FOUND error. The API consumer then knows they need to ask a different API provider about that MSISDN.

[yamamoto0104]

Hello @eric-murray

404 IDENTIFIER_NOT_FOUND is not applicable to this API. In this case, the API returns true in phoneNumChanged parameter.
Thus, I suggest to remove 404 IDENTIFIER_NOT_FOUND.

The description for IDENTIFIER_NOT_FOUND is:

Some identifier cannot be matched to a device

where you need to interpret "identifier" as "phone number" and "device" as "account" for this API.

So this is the error returned when the phone number is valid, but is not allocated to any of the API provider's customers or in the pool of numbers which could be allocated to customers. In other words, when the phone number actually belongs to a different network operator.

If the phone number is used by the API provider but the service does not apply (e.g. if a fixed line phone number is provided but the service is for mobile numbers only), then the error is 422 SERVICE_NOT_APPLICABLE.

[eric-murray]

404 IDENTIFIER_NOT_FOUND is not applicable to this API. In this case, the API returns true in phoneNumChanged parameter. Thus, I suggest to remove 404 IDENTIFIER_NOT_FOUND.

As explained above, some implementations will require this error if an operator receives a query about a MSISDN that is in use by a different operator, and that they therefore know nothing about. The API definition must be general enough to be used by all implementations.

[yamamoto0104]

@eric-murray
We are discussing this PR internally and will feedback next week.