You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Adopt the Commonalities r4.4 error response catalogue in sim-swap and sim-swap-subscriptions #296
With Commonalities r4.3, both APIs reference generic error responses that include codes which do not apply to them. Most visible in sim-swap-subscriptions (via Generic* from CAMARA_common.yaml and CreateSubscriptionUnprocessableEntity422 from CAMARA_event_common.yaml):
POST /subscriptions409: the deprecated CONFLICT next to INCOMPATIBLE_STATE
POST /subscriptions422: MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED and MULTIEVENT_COMBINATION_TEMPORARILY_NOT_SUPPORTED, although types has maxItems: 1; UNSUPPORTED_IDENTIFIER, which does not apply to a phone number as the only identifier
sim-swap references Generic400, Generic401, Generic404 and Generic429 from CAMARA_common.yaml and defines Generic403 and Generic422 locally.
Commonalities r4.4 (0.9.0) deprecates all Generic* responses and CreateSubscriptionUnprocessableEntity422, with removal planned for the next meta-release cycle, and provides a catalogue of minimal error responses that contain only codes every referencing API can return. API-specific code sets are defined locally from the shared examples. See the "CAMARA error responses — catalogue" and "DEPRECATED error responses" sections in CAMARA_common.yaml r4.4 and the r4.4 subscription API template.
Expected behavior
Update release-plan.yaml to commonalities_release: r4.4, merge the common files sync, and replace the error response references as follows.
sim-swap (/check and /retrieve-date):
Status
Current
r4.4
Effect on codes
400 (/check)
Generic400
BadRequestWithRange400
unchanged (INVALID_ARGUMENT, OUT_OF_RANGE for maxAge)
400 (/retrieve-date)
Generic400
BadRequest400
OUT_OF_RANGE removed (no range-restricted field)
401
Generic401
Unauthenticated401
unchanged
403
local Generic403
PermissionDenied403
unchanged, local definition removed
404
Generic404
IdentifierNotFound404
NOT_FOUND removed
422
local Generic422
PhoneNumberIdentifier422
unchanged, local definition removed, examples in phone number wording
429
Generic429
TooManyRequests429
QUOTA_EXCEEDED removed
sim-swap-subscriptions:
Operation
Status
Current
r4.4
Effect on codes
POST /subscriptions
400
CreateSubscriptionBadRequest400
unchanged
—
401
Generic401
Unauthenticated401
unchanged
403
SubscriptionPermissionDenied403
unchanged
—
409
Generic409
CreateSubscriptionConflict409
CONFLICT, INCOMPATIBLE_STATE removed
422
CreateSubscriptionUnprocessableEntity422
local definition from the shared examples: SERVICE_NOT_APPLICABLE, MISSING_IDENTIFIER, UNNECESSARY_IDENTIFIER, PRIVATE_KEY_JWT_NOT_CONFIGURED
UNSUPPORTED_IDENTIFIER, MULTIEVENT_* removed
429
Generic429
TooManyRequests429
QUOTA_EXCEEDED removed
GET /subscriptions
400
Generic400
BadRequest400, or BadRequestWithRange400 if OUT_OF_RANGE is returned for page/perPage
OUT_OF_RANGE (400) and QUOTA_EXCEEDED (429) removed
CreateSubscriptionPhoneNumber422 from CAMARA_event_common.yaml would keep the two MULTIEVENT_* codes, hence the local 422 definition for POST /subscriptions.
To decide:
QUOTA_EXCEEDED: if providers need it, define the 429 responses locally from GENERIC_429_TOO_MANY_REQUESTS and GENERIC_429_QUOTA_EXCEEDED.
sim-swap-subscriptions.feature, scenario @sim_swap_subscription_creation_100_not_applicable expects 422 UNSUPPORTED_IDENTIFIER for a phone number that does not support SIM swap subscriptions; with the phone number variant this is SERVICE_NOT_APPLICABLE.
Check that no scenario asserts a removed code (currently none found for CONFLICT, INCOMPATIBLE_STATE, INVALID_TOKEN_CONTEXT, QUOTA_EXCEEDED, NOT_FOUND in sim-swap, IDENTIFIER_NOT_FOUND in sim-swap-subscriptions).
Alternative solution
Keep the r4.3 references and define all trimmed responses locally. This duplicates definitions that the r4.4 catalogue already provides, and the deprecated Generic* responses are planned for removal.
Additional context
Found during the release review of r4.1 (#293). Removing codes from error responses does not break API consumers. The operation changes were checked with oasdiff changelog after replacing the references and syncing the r4.4 common files; the notification callback row is based on reading the response definitions.
Related: #288 (items 1 and 2: error code consistency and device vs. phone number wording between the two APIs).
The local 422 definition for POST /subscriptions should reference the phone number variants of the shared examples: GENERIC_422_SERVICE_NOT_APPLICABLE, GENERIC_422_MISSING_IDENTIFIER_PHONE_NUMBER and GENERIC_422_UNNECESSARY_IDENTIFIER_PHONE_NUMBER, plus GENERIC_422_PRIVATE_KEY_JWT_NOT_CONFIGURED from CAMARA_event_common.yaml. Together with PhoneNumberIdentifier422 in sim-swap, this aligns the 422 example messages of both APIs on phone number wording.
Syncing the r4.4 common files also adds the GENERIC_400_INVALID_TOKEN example to CreateSubscriptionBadRequest400. In r4.3 the code is listed without an example.
Removing INVALID_TOKEN_CONTEXT from the sim-swap-subscriptions 403 responses matches its info.description, which specifies 422 UNNECESSARY_IDENTIFIER when the phone number is also identified from the access token. Per the CAMARA API Design Guide r4.4, 403 INVALID_TOKEN_CONTEXT applies only when the API scope allows explicit confirmation whether the identifiers match.
With this, the PR for this issue resolves items 1 and 3 of #288 and the example wording part of item 2. Items 4–6 and the "device" wording in the info.description of sim-swap-subscriptions remain in #288.
Problem description
With Commonalities r4.3, both APIs reference generic error responses that include codes which do not apply to them. Most visible in
sim-swap-subscriptions(viaGeneric*fromCAMARA_common.yamlandCreateSubscriptionUnprocessableEntity422fromCAMARA_event_common.yaml):POST /subscriptions409: the deprecatedCONFLICTnext toINCOMPATIBLE_STATEPOST /subscriptions422:MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTEDandMULTIEVENT_COMBINATION_TEMPORARILY_NOT_SUPPORTED, althoughtypeshasmaxItems: 1;UNSUPPORTED_IDENTIFIER, which does not apply to a phone number as the only identifierGET/DELETEoperations403:INVALID_TOKEN_CONTEXTGET/DELETE /subscriptions/{subscriptionId}404:IDENTIFIER_NOT_FOUNDsim-swapreferencesGeneric400,Generic401,Generic404andGeneric429fromCAMARA_common.yamland definesGeneric403andGeneric422locally.Commonalities r4.4 (0.9.0) deprecates all
Generic*responses andCreateSubscriptionUnprocessableEntity422, with removal planned for the next meta-release cycle, and provides a catalogue of minimal error responses that contain only codes every referencing API can return. API-specific code sets are defined locally from the shared examples. See the "CAMARA error responses — catalogue" and "DEPRECATED error responses" sections in CAMARA_common.yaml r4.4 and the r4.4 subscription API template.Expected behavior
Update
release-plan.yamltocommonalities_release: r4.4, merge the common files sync, and replace the error response references as follows.sim-swap(/checkand/retrieve-date):/check)Generic400BadRequestWithRange400INVALID_ARGUMENT,OUT_OF_RANGEformaxAge)/retrieve-date)Generic400BadRequest400OUT_OF_RANGEremoved (no range-restricted field)Generic401Unauthenticated401Generic403PermissionDenied403Generic404IdentifierNotFound404NOT_FOUNDremovedGeneric422PhoneNumberIdentifier422Generic429TooManyRequests429QUOTA_EXCEEDEDremovedsim-swap-subscriptions:POST /subscriptionsCreateSubscriptionBadRequest400Generic401Unauthenticated401SubscriptionPermissionDenied403Generic409CreateSubscriptionConflict409CONFLICT,INCOMPATIBLE_STATEremovedCreateSubscriptionUnprocessableEntity422SERVICE_NOT_APPLICABLE,MISSING_IDENTIFIER,UNNECESSARY_IDENTIFIER,PRIVATE_KEY_JWT_NOT_CONFIGUREDUNSUPPORTED_IDENTIFIER,MULTIEVENT_*removedGeneric429TooManyRequests429QUOTA_EXCEEDEDremovedGET /subscriptionsGeneric400BadRequest400, orBadRequestWithRange400ifOUT_OF_RANGEis returned forpage/perPageOUT_OF_RANGEremoved withBadRequest400Generic401Unauthenticated401Generic403PermissionDenied403INVALID_TOKEN_CONTEXTremovedGET/DELETE /subscriptions/{subscriptionId}SubscriptionIdRequired400Generic401Unauthenticated401Generic403PermissionDenied403INVALID_TOKEN_CONTEXTremovedGeneric404NotFound404IDENTIFIER_NOT_FOUNDremovedGeneric400/Generic401/Generic403/Generic410/Generic429BadRequest400/Unauthenticated401/PermissionDenied403/SinkGone410/TooManyRequests429OUT_OF_RANGE(400) andQUOTA_EXCEEDED(429) removedCreateSubscriptionPhoneNumber422fromCAMARA_event_common.yamlwould keep the twoMULTIEVENT_*codes, hence the local 422 definition forPOST /subscriptions.To decide:
QUOTA_EXCEEDED: if providers need it, define the 429 responses locally fromGENERIC_429_TOO_MANY_REQUESTSandGENERIC_429_QUOTA_EXCEEDED.SUBSCRIPTION_MISMATCHonPOST /subscriptions403(fromSubscriptionPermissionDenied403): it was removed in r3.2 ([Sim-Swap-Subscriptions]: removeSUBSCRIPTION_MISMATCHerror-code #209). If that decision still holds, define the 403 locally withPERMISSION_DENIEDonly.Test definitions to align:
sim-swap-subscriptions.feature, scenario@sim_swap_subscription_creation_100_not_applicableexpects422 UNSUPPORTED_IDENTIFIERfor a phone number that does not support SIM swap subscriptions; with the phone number variant this isSERVICE_NOT_APPLICABLE.CONFLICT,INCOMPATIBLE_STATE,INVALID_TOKEN_CONTEXT,QUOTA_EXCEEDED,NOT_FOUNDinsim-swap,IDENTIFIER_NOT_FOUNDinsim-swap-subscriptions).Alternative solution
Keep the r4.3 references and define all trimmed responses locally. This duplicates definitions that the r4.4 catalogue already provides, and the deprecated
Generic*responses are planned for removal.Additional context
Found during the release review of r4.1 (#293). Removing codes from error responses does not break API consumers. The operation changes were checked with
oasdiff changelogafter replacing the references and syncing the r4.4 common files; the notification callback row is based on reading the response definitions.Related: #288 (items 1 and 2: error code consistency and device vs. phone number wording between the two APIs).