Skip to content

idDocument Management Error Scenarios #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
PedroDiez wants to merge 2 commits into
base: main
Choose a base branch
from
Open

idDocument Management Error Scenarios #65

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
460a9f5
idDocument Management Error Scenarios
PedroDiez Feb 12, 2026
e4a4f1f
fix_linter_errors
PedroDiez Feb 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 13 additions & 17 deletions code/API_definitions/customer-insights.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,18 @@ info:

- If the subject can be identified from the access token and the optional `phoneNumber` field is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same phone number is identified by these two methods, as the server is unable to make this comparison.

# Additional Information on Error scenarios

This section provides valuable information about the scope of some exceptions in order to provide support for the API implementation.

`422 - SERVICE_NOT_APPLICABLE`

This error code is used when the service cannot be provided. Applicable scenarios include, but are not limited to, the following:
- The API is invoked for a subscription, identified via access token or phoneNumber, that is not supported or not commercially allowed by the API Provider.
- The API is invoked for a valid subscription, identified via access token or phoneNumber, but the service cannot be provided for that specific subscription. For instance, this can be the case when the subscription has not enough historical data to provide a reliable Scoring result.
- The API is invoked without `idDocument` and the field is required by the API Provider.
- The API is invoked with a combination of `phoneNumber` and `idDocument`, considering `idDocument` is required by the API Provider, that does not point to the same subscription (i.e. the `phoneNumber` and `idDocument` provided are not related).

# Additional CAMARA error responses

The list of error codes in this API specification is not exhaustive. Therefore the API specification may not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`.
Expand Down Expand Up @@ -409,9 +421,7 @@ components:
- An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token ("code": "MISSING_IDENTIFIER","message": "The phone number cannot be identified.")
- An explicit identifier is provided when a device or phone number has already been identified from the access token ("code": "UNNECESSARY_IDENTIFIER","message": "The phone number is already identified by the access token.")
- Provided `scoringType` value is not supported. (`"code": "CUSTOMER_INSIGHTS.SCALE_TYPE_NOT_SUPPORTED","message": "Indicated parameter scoringType is not supported."`)
- Provided `idDocument` is not consistent with the phone number. (`"code": "CUSTOMER_INSIGHTS.INVALID_IDENTIFIERS","message": "The request contains invalid data."`)
- Provided `idDocument` field is not supported. (`"code": "CUSTOMER_INSIGHTS.ID_DOCUMENT_NOT_SUPPORTED","message": "Indicated parameter idDocument is not supported"`)
- Required `idDocument` field and it is not provided. (`"code": "CUSTOMER_INSIGHTS.ID_DOCUMENT_REQUIRED","message": "The idDocument is required to perform the properties validation."`)
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
Expand All @@ -431,9 +441,7 @@ components:
- MISSING_IDENTIFIER
- UNNECESSARY_IDENTIFIER
- CUSTOMER_INSIGHTS.SCALE_TYPE_NOT_SUPPORTED
- CUSTOMER_INSIGHTS.INVALID_IDENTIFIERS
- CUSTOMER_INSIGHTS.ID_DOCUMENT_NOT_SUPPORTED
- CUSTOMER_INSIGHTS.ID_DOCUMENT_REQUIRED
examples:
GENERIC_422_SERVICE_NOT_APPLICABLE:
description: Service not applicable for the provided identifier
Expand All @@ -459,24 +467,12 @@ components:
status: 422
code: CUSTOMER_INSIGHTS.SCALE_TYPE_NOT_SUPPORTED
message: Indicated parameter `scoringType` is not supported.
GENERIC_422_INVALID_IDENTIFIERS:
description: The request contains invalid data identifying customer
value:
status: 422
code: CUSTOMER_INSIGHTS.INVALID_IDENTIFIERS
message: The request contains invalid data.
GENERIC_422_ID_DOCUMENT_NOT_SUPPORTED:
description: Error when `idDocument` field is not supported
value:
status: 422
code: CUSTOMER_INSIGHTS.ID_DOCUMENT_NOT_SUPPORTED
message: Indicated parameter `idDocument` is not supported
GENERIC_422_ID_DOCUMENT_REQUIRED:
description: Error when `idDocument` field is not provided and it is required.
value:
status: 422
code: CUSTOMER_INSIGHTS.ID_DOCUMENT_REQUIRED
message: The `idDocument` is required to perform the properties validation.
message: Indicated parameter `idDocument` is not supported.
Generic429:
description: Too Many Requests
headers:
Expand Down
17 changes: 10 additions & 7 deletions code/Test_definitions/customer-insights-retrieveScoring.feature
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ Feature: CAMARA Customer Insights API, vwip - Operation retrieveScoring

@retrieve_scoring_C02.01_phone_number_not_schema_compliant
Scenario: Phone number value does not comply with the schema
Given the header "Authorization" is set to a valid access which does not identify a single phone number
Given the header "Authorization" is set to a valid access token which does not identify a single phone number
And the request body property "$.phoneNumber" does not comply with the OAS schema at "/components/schemas/PhoneNumber"
When the request "retrieveScoring" is sent
Then the response status code is 400
Expand Down Expand Up @@ -164,8 +164,11 @@ Feature: CAMARA Customer Insights API, vwip - Operation retrieveScoring

@retrieve_scoring_404.01_idDocument_not_found
Scenario: idDocument not found
# To test this, a 3-legged access token is needed, just because if not it triggers test "@retrieve_scoring_C02.04_missing_phone_number"
# Scenario applicable for a Telco Operator that requires `idDocument` for scoring retrieval.
# In case `idDocument` is not a required field for the Telco Operator, applicable scenarios are "@retrieve_scoring_422.03_id_document_not_supported_three_legged" and "@retrieve_scoring_422.04_id_document_not_supported_two_legged".
Given the header "Authorization" is set to a valid access token identifying a phone number
And the request body property "$.idDocument" is set to a valid value not existing in the environment
And the request body property "$.idDocument" is required and set to a valid value not existing in the environment
When the request "retrieveScoring" is sent
Then the response status code is 404
And the response property "$.status" is 404
Expand Down Expand Up @@ -203,7 +206,7 @@ Feature: CAMARA Customer Insights API, vwip - Operation retrieveScoring
When the request "retrieveScoring" is sent
Then the response status code is 422
And the response property "$.status" is 422
And the response property "$.code" is "CUSTOMER_INSIGHTS.INVALID_IDENTIFIERS"
And the response property "$.code" is "SERVICE_NOT_APPLICABLE"
And the response property "$.message" contains a user friendly text

@retrieve_scoring_422.03_id_document_not_supported_three_legged
Expand Down Expand Up @@ -271,7 +274,7 @@ Feature: CAMARA Customer Insights API, vwip - Operation retrieveScoring
When the request "retrieveScoring" is sent
Then the response status code is 422
And the response property "$.status" is 422
And the response property "$.code" is "CUSTOMER_INSIGHTS.ID_DOCUMENT_REQUIRED"
And the response property "$.code" is "SERVICE_NOT_APPLICABLE"
And the response property "$.message" contains a user friendly text

@retrieve_scoring_422.08_id_document_required_two_legged
Expand All @@ -283,7 +286,7 @@ Feature: CAMARA Customer Insights API, vwip - Operation retrieveScoring
When the request "retrieveScoring" is sent
Then the response status code is 422
And the response property "$.status" is 422
And the response property "$.code" is "CUSTOMER_INSIGHTS.ID_DOCUMENT_REQUIRED"
And the response property "$.code" is "SERVICE_NOT_APPLICABLE"
And the response property "$.message" contains a user friendly text

@retrieve_scoring_422.09_id_document_required_three_legged_with_scoring_type
Expand All @@ -296,7 +299,7 @@ Feature: CAMARA Customer Insights API, vwip - Operation retrieveScoring
When the request "retrieveScoring" is sent
Then the response status code is 422
And the response property "$.status" is 422
And the response property "$.code" is "CUSTOMER_INSIGHTS.ID_DOCUMENT_REQUIRED"
And the response property "$.code" is "SERVICE_NOT_APPLICABLE"
And the response property "$.message" contains a user friendly text

Examples:
Expand All @@ -314,7 +317,7 @@ Feature: CAMARA Customer Insights API, vwip - Operation retrieveScoring
When the request "retrieveScoring" is sent
Then the response status code is 422
And the response property "$.status" is 422
And the response property "$.code" is "CUSTOMER_INSIGHTS.ID_DOCUMENT_REQUIRED"
And the response property "$.code" is "SERVICE_NOT_APPLICABLE"
And the response property "$.message" contains a user friendly text

Examples:
Expand Down
Loading