Informative - Business-Level Outcome 2xx vs 4xx scenarios

As an output from CAMARA Commonalities PR#578 Add business-level outcome guidance to API Design Guide, an issue is open to discuss about scenarios where 2xx or 4xx is the suitable option.

Main HTTP Error Statuses to be analysed are the ones related to common API functionality (*):

400
401
403
404
409
422

(*) Errors 405, 406, 410, 412, 415, 429 do not collide with 2xx scenarios

HTTP Error status	Scope	Illustratives Examples	Collision with Business-level Outcomes in 2xx Successful Responses Scenarios

HTTP Error status	Scope	Illustratives Examples	Collision with Business-level Outcomes in 2xx Successful Responses Scenarios
400	Client Syntax Exception	`400 - INVALID_ARGUMENT` `400 - OUT_OF_RANGE`	NO (API Consumer syntax error, API Provider can never process the API Request)
401	Client Request cannot be authenticated	`401 - UNAUTHENTICATED`	NO (API Consumer Auth error, API Provider can never process the API Request)
403	Security (client does not have sufficient permissions) OR Business Logic condition that forbids a process	`403 - PERMISSION_DENIED` `403 - CARRIER_BILLING.PAYMENT_DENIED`	NO (API Consumer error without right permissions or under forbidden business logic, API Provider can never process the API Request)
404	Resource is not found	`404 - NOT_FOUND` `404 - IDENTIFIER_NOT_FOUND`	NO (API Consumer error, providing a non-existing resouce, API Provider can never process the API Request)
409	Conflict situation with the involved resource/s	`409 - ALREADY_EXISTS` `409 - INCOMPATIBLE_STATE`	NO (API Consumer error, providing a non-working resource, API Provider can never process the API Request)
422	Any semantic condition associated to business logic, specifically related to a field or data structure	`422 - UNNECESSARY_IDENTIFIER` `422 - MISSING_IDENTIFIER` `422 - SERVICE_NOT_APPLICABLE` `422 - QUALITY_ON_DEMAND.QOS_PROFILE_NOT_APPLICABLE`	YES. `422` error semantics indicates that the server understands the content type of the request content, and the syntax of the request content is correct, but it was unable to process the contained instructions. This consideration may overlap the 2xx status indicating that the request was valid and processed. These are the kind of scenarios that we need to analyse deeper.

Analysis 422 vs 2xx

In this section, 422 scenarios are analysed considering current exceptions in several APIs (considering stable ones).
Objective is to identify scenarios where 2xx or 422 are the suitable way forward.

API NAME	OperationId	ERROR 422 CODE	Scenario	¿Overlap with 2xx?

API NAME	OperationId	ERROR 422 CODE	Scenario	¿Overlap with 2xx?
device-reachability-status / device-roaming-status	getReachabilityStatus / getRoamingStatus	UNNECESSARY_IDENTIFIER	Indication of device/phoneNumber in 3-legged scenario	NO
		MISSING_IDENTIFIER	Missing of device/phoneNumber in 2-legged scenario	NO
		SERVICE_NOT_APPLICABLE	Subscription/Segment not supported in the API provider (e.g. funcionality not supported for Fixed Lines) Subscription/Segment not commercially delivered by the API Provider (e.g. funcionality not delivered for Prepaid Lines)	NO
		UNSUPPORTED_IDENTIFIER	Provided identifier is not supported by the API Provider implementation (e.g. API provider does not support IPv6)	NO
location-verification	verifyLocation	UNNECESSARY_IDENTIFIER	Indication of device/phoneNumber in 3-legged scenario	NO
		MISSING_IDENTIFIER	Missing of device/phoneNumber in 2-legged scenario	NO
		SERVICE_NOT_APPLICABLE	Subscription/Segment not supported in the API provider (e.g. funcionality not supported for Fixed Lines) Subscription/Segment not commercially delivered by the API Provider (e.g. funcionality not delivered for Prepaid Lines)	NO
		UNSUPPORTED_IDENTIFIER	Provided identifier is not supported by the API Provider implementation (e.g. API provider does not support IPv6)	NO
		LOCATION_VERIFICATION.AREA_NOT_COVERED	Field value not supported by the implementation	NO
		LOCATION_VERIFICATION.INVALID_AREA	Field value not supported by the implementation	NO
		LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE	Field value that triggers a business condition where service cannot be performed/delivered (aligned within API initiative)	NO
		LOCATION_VERIFICATION.UNABLE_TO_LOCATE	API request that triggers a business condition where service cannot be performed/delivered	MAYBE
qos-profiles	retrieveQoSProfiles	UNNECESSARY_IDENTIFIER	Indication of device/phoneNumber in 3-legged scenario	NO
		SERVICE_NOT_APPLICABLE	Subscription/Segment not supported in the API provider Subscription/Segment not commercially delivered by the API Provider	NO
		UNSUPPORTED_IDENTIFIER	Provided identifier is not supported by the API Provider implementation	NO
quality-on-demand	createSession	UNNECESSARY_IDENTIFIER	Indication of device/phoneNumber in 3-legged scenario	NO
		MISSING_IDENTIFIER	Missing of device/phoneNumber in 2-legged scenario	NO
		SERVICE_NOT_APPLICABLE	Subscription/Segment not supported in the API provider Subscription/Segment not commercially delivered by the API Provider	NO
		UNSUPPORTED_IDENTIFIER	Provided identifier is not supported by the API Provider implementation	NO
		QUALITY_ON_DEMAND.QOS_PROFILE_NOT_APPLICABLE	Concept/Resource in the context of the API that is in an status where service cannot be performed/delivered	NO
	retrieveSessionsByDevice	UNNECESSARY_IDENTIFIER	Indication of device/phoneNumber in 3-legged scenario	NO
		MISSING_IDENTIFIER	Missing of device/phoneNumber in 2-legged scenario	NO
		SERVICE_NOT_APPLICABLE	Subscription/Segment not supported in the API provider Subscription/Segment not commercially delivered by the API Provider	NO
		UNSUPPORTED_IDENTIFIER	Provided identifier is not supported by the API Provider implementation	NO
sim-swap	checkSimSwap / retrieveSimSwapDate	UNNECESSARY_IDENTIFIER	Indication of device/phoneNumber in 3-legged scenario	NO
		MISSING_IDENTIFIER	Missing of device/phoneNumber in 2-legged scenario	NO
		SERVICE_NOT_APPLICABLE	Subscription/Segment not supported in the API provider Subscription/Segment not commercially delivered by the API Provider	NO
simple-edge-discovery	readClosestEdgeCloudZone	UNNECESSARY_IDENTIFIER	Indication of device/phoneNumber in 3-legged scenario	NO
		MISSING_IDENTIFIER	Missing of device/phoneNumber in 2-legged scenario	NO
		SERVICE_NOT_APPLICABLE	Subscription/Segment not supported in the API provider Subscription/Segment not commercially delivered by the API Provider	NO
		UNSUPPORTED_IDENTIFIER	Provided identifier is not supported by the API Provider implementation	NO
device-swap	checkDeviceSwap / retrieveDeviceSwapDate	UNNECESSARY_IDENTIFIER	Indication of device/phoneNumber in 3-legged scenario	NO
		MISSING_IDENTIFIER	Missing of device/phoneNumber in 2-legged scenario	NO
		SERVICE_NOT_APPLICABLE	Subscription/Segment not supported in the API Provider Subscription/Segment not commercially delivered by the API Provider	NO
carrier-billing	cancelPayment	UNNECESSARY_IDENTIFIER	Indication of device/phoneNumber in 3-legged scenario	NO
		MISSING_IDENTIFIER	Missing of device/phoneNumber in 2-legged scenario	NO
		SERVICE_NOT_APPLICABLE	Subscription/Segment not supported in the API Provider Subscription/Segment not commercially delivered by the API Provider	NO
	confirmPayment	UNNECESSARY_IDENTIFIER	Indication of device/phoneNumber in 3-legged scenario	NO
		MISSING_IDENTIFIER	Missing of device/phoneNumber in 2-legged scenario	NO
		SERVICE_NOT_APPLICABLE	Subscription/Segment not supported in the API Provider Subscription/Segment not commercially delivered by the API Provider	NO
	createPayment	UNNECESSARY_IDENTIFIER	Indication of device/phoneNumber in 3-legged scenario	NO
		MISSING_IDENTIFIER	Missing of device/phoneNumber in 2-legged scenario	NO
		SERVICE_NOT_APPLICABLE	Subscription/Segment not supported in the API Provider Subscription/Segment not commercially delivered by the API Provider	NO
		CARRIER_BILLING.UNAUTHORIZED_AMOUNT	Field value that triggers a business condition where service cannot be performed/delivered (aligned within API initiative)	NO
		CARRIER_BILLING.USER_AMOUNT_THRESHOLD_OVERPASSED	Business condition where service cannot be performed/delivered, not changing in time (aligned within API initiative)	NO
	preparePayment	UNNECESSARY_IDENTIFIER	Indication of device/phoneNumber in 3-legged scenario	NO
		MISSING_IDENTIFIER	Missing of device/phoneNumber in 2-legged scenario	NO
		SERVICE_NOT_APPLICABLE	Subscription/Segment not supported in the API Provider Subscription/Segment not commercially delivered by the API Provider	NO
		CARRIER_BILLING.UNAUTHORIZED_AMOUNT	Field value that triggers a business condition where service cannot be performed/delivered (aligned within API initiative)	NO
		CARRIER_BILLING.USER_AMOUNT_THRESHOLD_OVERPASSED	API request that that triggers a business condition where service cannot be performed/delivered (aligned within API initiative)	NO
carrier-billing-refund	createRefund	CARRIER_BILLING_REFUND.INVALID_PAYMENT_STATUS	Concept/Resource in the context of the API that is in an status where service cannot be performed/delivered	NO
		CARRIER_BILLING_REFUND.REFUND_DETAILS_MISMATCH	Inconsistent field/structure value(s) to operate over a resource	NO
		CARRIER_BILLING_REFUND.TAXES_MANAGEMENT_MISMATCH	Inconsistent field/structure value(s) to operate over a resource	NO
		CARRIER_BILLING_REFUND.UNAUTHORIZED_AMOUNT	Field value that triggers a business condition where service cannot be performed/delivered (aligned within API initiative)	NO
		CARRIER_BILLING_REFUND.USER_AMOUNT_THRESHOLD_OVERPASSED	Business condition where service cannot be performed/delivered, not changing in time (aligned within API initiative)	NO
kyc-tenure	checkTenure	UNNECESSARY_IDENTIFIER	Indication of device/phoneNumber in 3-legged scenario	NO
		MISSING_IDENTIFIER	Missing of device/phoneNumber in 2-legged scenario	NO
		SERVICE_NOT_APPLICABLE	Subscription/Segment not supported in the API provider (e.g. funcionality not supported for Fixed Lines) Subscription/Segment not commercially delivered by the API Provider (e.g. funcionality not delivered for Prepaid Lines)	NO
location-retrieval	retrieveLocation