Operational failure scenarios and error handling

Introduction

Overview

This document provides guidance for pension providers, schemes and integrated service providers (ISPs) in delivering a stable, reliable and seamless experience for dashboard users. It sets out clear expectations for how pension providers and schemes should behave in 2 critical areas of the ecosystem:

1. Operational failure scenarios: Guidance for a category of failure scenarios that fall outside standard API and error handling.
2. Error handling: A consistent approach to interpreting, returning and responding to error conditions, ensuring predictable behaviour across all components within the ecosystem.

The aim of this guidance is to promote predictable behaviour, aligned response patterns and reliable retry mechanisms across the ecosystem. It is important that pension providers and schemes approach error handling and PeI registration failures consistently to ensure operational stability and to support a good dashboard user experience. To support this, the guidance builds upon the published technical standards and introduces clearer definitions, extended error scenarios and recommended retry patterns that pension providers and schemes should adopt. Elements of this guidance may be considered for inclusion within future updates of the technical standards.

By following these recommendations, pension providers and schemes can help ensure consistency across the PDP ecosystem and maintain trust in the dashboards service.

Error handling: background

This guidance aligns with and expands upon the structure presented in the ‘Sequences diagrams and API usage’ section of the published PDP technical standards. The technical standards describe 4 primary use cases, including:

• Pension provider or scheme – match pensions and register PeIs
• Pension provider or scheme – update match status
• Pension provider or scheme – delete registered PeI and
• Pension provider or scheme – get view data request

While the standards define the baseline success and error responses for each API, additional clarification is required to ensure consistency of implementation across the ecosystem. This guidance introduces more detailed scenarios, recommends additional response codes where appropriate, and specifies explicit retry expectations that support operational stability.

Operational failure scenarios

Overview

This section describes a set of failure scenarios that cannot be addressed solely through standard request/response patterns or error codes. Such scenarios typically arise after a request has been accepted by the pension provider or scheme and relate to operational issues such as system availability, timing or recovery, rather than request validation or API interaction.

The scenarios grouped in this section are intended to support consistent provider behaviour and reduce the risk of partial or inconsistent system states. Additional scenarios of this nature may be identified over time and added to this section.

Scenarios

• PeI registration failure

PeI registration failure

Overview

During the processing of a find request, a pension provider or scheme may experience an outage after receiving and acknowledging a find request. This section explains the resulting risks, constraints and required behaviours to ensure minimum impact to citizens.

Failure scenario description

A standard find request begins when a user submits the request. The pension finder service (PFS) transmits the request to pension providers or schemes along with the required user account token (UAT). Providers acknowledge receipt of the request (unless they are offline) and begin the pension matching process.

If the pension provider or scheme identifies a definite or possible match, it must register a pension identifier (PeI) within the defined service level (see CoCo2.1.2). PeI registration requires the provider to:

• use the UAT to obtain a Protection API Token (PAT) and
• use the PAT to register the PeI within the central digital architecture (CDA)

If a provider experiences downtime after acknowledging the find request and subsequently returns online after the UAT has expired, the provider cannot obtain a PAT and is therefore unable to register any identified matches.

Expected behaviour

If a provider returns online after the UAT has expired and cannot complete PeI registration, the following behaviour is recommended:

• Subsequent find requests should be treated as new: Providers should act as though no PeIs were registered during the previous attempt.
• Partial states should not be persisted: Any matches identified during the failed registration should be treated as not registered with the CDA.
• Earlier unregistered matches should not block future processing: Providers should ensure system logic does not assume a PeI exists when registration did not occur. A locally generated but unregistered PeI should not be treated as active or associated with the user.

Following these recommendations ensures that future find request can be processed successfully and that provider systems remain aligned with the CDA, eliminating the risk of PeIs remaining unregistered because of a registration failure.

Error handling: APIs and use cases

This section summarises the APIs associated with the four use cases and sets out the recommended success and error response codes. Where an HTTP response code is already defined within the published technical standards, this document labels it as existing. Any additional codes or scenarios introduced through this guidance are labelled as new.

Summary of APIs and HTTP codes

1. Pension provider or scheme – match pensions and register PeIs

• find-requests (POST)
  • Existing HTTP codes: 202, 400, 403 or 400 or connection refused/reject handshake
  • New HTTP codes: 400 (with more specific scenarios), 404, 405, 415 or 400, 429, 502 or 500, 503 or 500
• token (POST)
  • Existing HTTP codes: 200
  • New HTTP codes: 400, 403, 500, 503, 504
• rreguri (POST)
  • Existing HTTP codes: 201
  • New HTTP codes: 200 (for already registered PeIs), 400, 401, 404, 429, 500, 503, 504

2. Pension provider or scheme – update match status

• rreguri (PATCH)
  • Existing HTTP codes: 200
  • New HTTP codes: 400, 401, 404, 500, 503, 504

3. Pension provider or scheme – delete registered PeI

• rreguri (DELETE)
  • Existing HTTP codes: 204
  • New HTTP codes: 400, 401, 404, 500, 503, 504

4. Pension provider or scheme – get view data request

• view-data (GET)
  • Existing HTTP codes: 200, 401, 403 or 400 or connection refused/reject handshake
  • New HTTP codes: 400, 401 (for invalid RPT and more scenarios), 404, 405 or 400, 415 or 400, 429 or 400, 502 or 500, 503 or 500
• introspect (POST)
  • Existing HTTP codes: 200
  • New HTTP codes: 400, 401, 500, 503, 504
• perm (POST)
  • Existing HTTP codes: 201
  • New HTTP codes: 400, 401, 500, 503, 504

Error handling: recommendations and retry approaches

This section outlines the primary use cases relevant to pension providers and schemes along with the associated APIs. For each API, it presents the recommended error handling approaches and the corresponding response patterns. In some cases, multiple scenarios may apply to a single HTTP status code.

Use case 1: Pension provider or scheme – match pensions and register PeIs

Relevant APIs

• find-requests (POST)
• token (POST)
• rreguri (POST)

find-requests API (POST)

This is an API hosted by pension providers and schemes aimed to accept find requests by the CDA.

Hosted by: Pension providers or schemes.

Called by: CDA.

Success responses – (202 Accepted):

• General principle: For successful receipt of a request, the pension provider or scheme should return 202 Accepted as an acknowledgement.
• Scenarios:
  • Provider response acknowledgement: Request received by pension provider or scheme.
• Response: Return 202 Accepted.
• Issued by: Pension provider or scheme.

Error responses – (400 Bad Request):

• General principle: In the following scenarios, the pension provider should return 400 Bad Request. The CDA will not retry these scenarios.
• Scenarios:
  • Missing or invalid ‘find correlation ID’: find_correlation_id is missing or invalid in the header.
  • Missing or invalid ‘X-Request-ID': X-Request-ID is missing or invalid in the header.
  • Missing or invalid ‘User Account Token’: user_account_token is missing or invalid in the body.
  • Missing or invalid ‘User Token’: user_token is missing or invalid in the body.
• Response: Return 400 Bad Request for all scenarios above.
• Issued by: Pension provider or scheme.
• Retry behaviour: CDA will not retry in these scenarios.

Error responses – (403 Forbidden or 400 Bad Request):

• General principle: For mTLS-related errors where the client certificate is missing or invalid, the provider should return 403 Forbidden (preferred) or 400 Bad Request if 403 is not supported. If neither option is possible, use a transport-level error. The CDA will not retry these scenarios.
• Scenarios:
  • Missing or invalid Client Certificate: The client certificate for the request is missing or invalid.
• Response: Return 403 Forbidden (preferred) or 400 Bad Request. If not supported, use a transport-level error for example, “connection refused”.
• Issued by: Pension provider or scheme.
• Retry behaviour: CDA will not retry in this scenario.

Error responses – (404 Resource Not Found)

• General principle: For incorrect URLs, the pension provider should return 404 Resource Not Found. The CDA will not retry these scenarios.
• Scenarios:
  • Incorrect URL: The URL is incorrect or the wrong HTTP method was used on the request.
• Response: Return 404 Resource Not Found.
• Issued by: Pension provider or scheme.
• Retry behaviour: CDA will not retry in this scenario.

Error responses – (405 Method Not Allowed or 400 Bad Request):

• General principle: For method not allowed, the pension provider should return 405 Method Not Allowed (preferred) or 400 Bad Request if 405 is not supported. The CDA will not retry these scenarios.
• Scenarios:
  • Wrong method used on submission: The CDA invokes the find-requests endpoint using an HTTP method that is not supported.
• Response: Return 405 Method Not Allowed (preferred) or 400 Bad Request.
• Issued by: Pension provider or scheme.
• Retry behaviour: The CDA will not retry in this scenario.

Error responses – (415 Unsupported Media type or 400 Bad Request)

• General principle: For incorrect content type, return 415 Unsupported Media Type (preferred) or 400 Bad Request if 415 is not supported. The CDA will not retry these scenarios.
• Scenarios:
  • Missing or invalid Content-Type: Content-Type header is missing or incorrect (for example, not application/json;charset=UTF-8).
• Response: Return 415 Unsupported Media Type (preferred) or 400 Bad Request.
• Issued by: Pension provider or scheme.
• Retry behaviour: CDA will not retry in this scenario.

Error responses – (429 Too Many Requests)

• General principle: For excessive requests, return 429 Too Many Requests. The CDA will retry using a linear backoff policy.
• Scenarios:
  • Too many requests: Too many requests made within a short period.
• Response: Return 429 Too Many Requests.
• Issued by: Pension provider or scheme.
• Retry behaviour: CDA will retry using a linear backoff policy as follows:
  • First retry: after 5 seconds
  • Second retry: after 10 seconds
  • Third retry: after 15 seconds

Error responses – (502 Bad Gateway or 500 Internal Server Error)

• General principle: For API Gateway issues, return 502 Bad Gateway (preferred) or 500 Internal Server Error if 502 is not supported. The CDA will retry using a linear backoff policy.
• Scenarios:
  • Provider API Gateway down: API Gateway is unavailable.
• Response: Return 502 Bad Gateway (preferred) or 500 Internal Server Error.
• Issued by: Pension provider or scheme.
• Retry behaviour: CDA will retry using a linear backoff policy as follows:
  • First retry: after 5 seconds
  • Second retry: after 10 seconds
  • Third retry: after 15 seconds

Error responses – (503 Service Unavailable or 500 Internal Server Error)

• General principle: For maintenance, return 503 Service Unavailable (preferred) or 500 Internal Server Error if 503 is not supported. The CDA will retry using a linear backoff policy.
• Scenarios:
  • Provider maintenance: Planned or unplanned maintenance.
• Response: Return 503 Service Unavailable (preferred) or 500 Internal Server Error.
• Issued by: Pension provider or scheme.
• Retry behaviour: CDA will retry using a linear backoff policy as follows:
  • First retry: after 5 seconds
  • Second retry: after 10 seconds
  • Third retry: after 15 seconds

token API (POST)

This is an API hosted by the CDA with a purpose of assisting pension providers and schemes to obtain tokens.

Hosted by: CDA.

Called by: Pension providers or schemes.

Success responses – (200 OK):

• General principle: When CDA successfully issues a token, the pension provider or scheme will receive a 200 OK response containing the required fields.
• Scenarios:
  • Access Token and Token Type: access_token is issued by the CDA in the response body. token_type value is “pension_dashboard_pat”.
• Response: Return 200 OK.
• Issued by: CDA.
• Parameters returned:
  • access_token (body)
  • token_type (body)

Error responses – (400 Bad Request):

• General principle: In the following scenarios, the CDA will return 400 Bad Request. The pension provider or scheme should not retry these scenarios.
• Scenarios:
  • Missing or invalid ‘X-Request-ID': X-Request-ID is missing or invalid in the header.
  • Missing or invalid ‘grant_type’: grant_type is missing or invalid in the body or is not jwt-bearer.
  • Missing or invalid assertion (‘User Account Token’): assertion (for example, value of user_account_token) is missing or invalid in the body.
  • Scope does not match UMA protection: scope is missing or invalid (for example, does not match UMA protection requirements) in the body.
• Response: Return 400 Bad Request for all scenarios above.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should not retry in these scenarios.

Error responses – (403 Forbidden):

• General principle: For incorrect content type, the CDA will return 403 Forbidden. The pension provider or scheme should not retry these scenarios.
• Scenarios:
  • Missing or invalid Content-Type: Content-Type header is missing or incorrect (for example, not application/json;charset=UTF-8).
• Response: Return 403 Forbidden.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should not retry in this scenario.

Error responses – (500 Internal Server Error)

• General principle: For unexpected server-side failures, the CDA will return 500 Internal Server Error. The pension provider or scheme should retry using the defined backoff.
• Scenarios:
  • Unexpected server error: Any unexpected server-side failure occurs during processing.
• Response: Return 500 Internal Server Error.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should retry with:
  • Base interval: 5000 ms
  • Exponential factor: 2
  • Max retries: 4
• The UAT time-to-live is 120 seconds, which allows the PAT to be obtained within 4 retries, up to approximately 80 seconds.

Error responses – (503 Service Unavailable)

• General principle: For unexpected server-side unavailability, the CDA will return 503 Service Unavailable. The pension provider or scheme should retry using the defined backoff.
• Scenarios:
  • Temporary server unavailability: Any temporary server-side unavailability due to maintenance or availability constraints.
• Response: Return 503 Service Unavailable.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should retry with:
  • Base interval: 5000 ms
  • Exponential factor: 2
  • Max retries: 4

Error responses – (504 Gateway Timeout)

• General principle: For unexpected server-side timeouts, the CDA will return 504 Gateway Timeout. The pension provider or scheme should retry using the defined backoff.
• Scenarios:
  • Downstream timeout: Any temporary timeout when communicating with a downstream CDA service.
• Response: Return 504 Gateway Timeout.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should retry with:
  • Base interval: 5000 ms
  • Exponential factor: 2
  • Max retries: 4

rreguri API (POST)

This is an API hosted by the CDA with a purpose of assisting pension providers and schemes to register PeIs.

Hosted by: CDA.

Called by: Pension providers or schemes.

Success responses – (200 OK):

• General principle: If a PeI is already registered for the pension owner, the CDA will return 200 OK to indicate no new registration was created.
• Scenarios:
  • Already Registered PeI: The pension provider or scheme attempts to register a PeI that already exists for that user.
• Response: Return 200 OK.
• Issued by: CDA.
• Parameters returned:
  • Location (header)
  • resource_id (body)

Success responses – (201 Created):

• General principle: When CDA successfully registers a PeI, the pension provider or scheme will receive a 201 Created response containing the details of the newly created resource.
• Scenarios:
  • Newly Registered PeI: A new PeI has been successfully registered.
• Response: Return 201 Created.
• Issued by: CDA.
• Fields returned:
  • Location (header)
  • resource_id (body)

Error responses – (400 Bad Request):

• General principle: In the following scenarios, the CDA will return 400 Bad Request. The pension provider or scheme should not retry these scenarios.
• Scenarios: [applicable only to rreguri POST]
  • Missing ‘description’: The ‘description’ is missing in the body.
  • Missing ‘Name’: The ‘Name’ is missing in the body.
  • Incorrect values for ‘resource_scopes’: ‘resource_scopes’ is not set to [“value”, “owner”, “delegate“].
• Response: Return 400 Bad Request for all scenarios above.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should not retry in these scenarios.

Error responses – (404 Resource Not Found)

• General principle: For incorrect URLs or wrong HTTP methods, the CDA will return 404 Resource Not Found. The pension provider or scheme should not retry these scenarios.
• Scenarios: [applicable only to rreguri POST]
  • Holder name is not found: The holdernameGuid could not be found.
• Response: Return 404 Resource Not Found.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should not retry in these scenarios.

Error responses – (429 Too Many Requests)

• General principle: When too many registration requests are made to the CDA within a short period of time, the CDA return 429 Too Many Requests. The pension provider or scheme should retry using the defined backoff.
• Scenarios: [applicable only to rreguri POST]
  • Making too many PeI registration requests within a period of time: The pension provider or scheme has exceeded the allowed request limit.
• Response: Return 429 Too Many Requests.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should retry with:
  • Base interval: 5000 ms
  • Exponential factor: 2
  • Max retries: 12

Use case 2: Pension provider or scheme – update match status

Relevant APIs

• rreguri (PATCH)

rreguri API (PATCH)

This is an API hosted by the CDA with a purpose of assisting pension providers and schemes to update and maintain PeIs.

Hosted by: CDA.

Called by: Pension providers or schemes.

Success responses – (200 OK):

• General principle: If a PeI is already registered for the pension owner, the CDA will return 200 OK to indicate that the existing registration has been updated.
• Scenarios:
  • Existing PeI – Match Status Update: The pension provider or scheme submits a request for a PeI that already exists, typically to update the match status of an existing registration.
• Response: Return 200 OK.
• Issued by: CDA.
• Parameters returned:
  • resource_id (body)

Error responses – (400 Bad Request):

• General principle: In the following scenarios, the CDA will return 400 Bad Request. The pension provider or scheme should not retry these scenarios.
• Scenarios: [applicable to rreguri POST and PATCH]
  • New registrations submitted for disconnected schemes or part schemes: A new registration request related to a disconnected or part-disconnected scheme.
  • Modifications to existing registrations for disconnected schemes or part schemes: A modification request for an existing registration relates to a disconnected or part-disconnected scheme.
  • Invalid match status: The match status provided is not ‘match-yes’ or ‘match-possible’.
  • Invalid ‘inbound_request_id’: The ‘inbound_request_id’ is invalid in the body.
• Response: Return 400 Bad Request for all scenarios above.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should not retry in these scenarios.

Use case 3: Pension provider or scheme – delete registered PeI

Relevant APIs

• rreguri (DELETE)

rreguri API (DELETE)

This is an API hosted by the CDA with a purpose of assisting pension providers and schemes to delete PeIs.

Hosted by: CDA.

Called by: Pension providers or schemes.

Success responses – (204 No Content):

• General principle: When CDA successfully deletes a PeI, the pension provider or scheme will receive a 204 No Content.
• Scenarios:
  • Deleted PeI: An existing PeI has been successfully deleted.
• Response: Return 204 No Content.
• Issued by: CDA.

Error responses – (400 Bad Request):

• General principle: In the following scenarios, the CDA will return 400 Bad Request. The pension provider or scheme should not retry these scenarios.
• Scenarios: [applicable only to rreguri DELETE]
  • Missing or invalid ‘deletion_reason’ query parameter: The ‘deletion_reason’ query parameter is missing or invalid.
• Scenarios: [applicable to rreguri PATCH and DELETE]
  • Missing or invalid ‘resource_id’ path parameter: The resource_id in the request path is missing or invalid.
• Scenarios: [applicable to all rreguri HTTP methods; POST, PATCH and DELETE]
  • Missing or invalid ‘X-Request-ID': X-Request-ID is missing or invalid in the header.
  • Missing or invalid ‘Authorization’ header: The Authorization header is missing or invalid.
• Response: Return 400 Bad Request for all scenarios above.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should not retry in these scenarios.

Error responses – (401 Unauthorized)

• General principle: For unauthorized PAT used on the request, the CDA return 401 Unauthorized. The pension provider or scheme should not retry these scenarios.
• Scenarios: [applicable to all rreguri HTTP methods; POST, PATCH and DELETE]
  • Unauthorized PAT: An unauthorized PAT was used on the request.
• Response: Return 401 Unauthorized.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should not retry in these scenarios.

Error responses – (404 Resource Not Found)

• General principle: For incorrect URLs or wrong HTTP methods, the CDA return 404 Resource Not Found. The pension provider or scheme should not retry these scenarios.
• Scenarios: [applicable to all rreguri HTTP methods; POST, PATCH and DELETE]
  • Incorrect URL: The URL is incorrect or the wrong HTTP method was used on the request.
• Response: Return 404 Resource Not Found.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should not retry in these scenarios.

Error responses – (500 Internal Server Error)

• General principle: For unexpected server-side failures, the CDA will return 500 Internal Server Error. The pension provider or scheme should retry using the defined backoff.
• Scenarios: [applicable to all rreguri HTTP methods; POST, PATCH and DELETE]
  • Unexpected server error: Any unexpected server-side failure occurs during processing.
• Response: Return 500 Internal Server Error.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should retry with:
  • Base interval: 5000 ms
  • Exponential factor: 2
  • Max retries: 12

Error responses – (503 Service Unavailable)

• General principle: For unexpected server-side unavailability, the CDA will return 503 Service Unavailable. The pension provider or scheme should retry using the defined backoff.
• Scenarios: [applicable to all rreguri HTTP methods; POST, PATCH and DELETE]
  • Temporary server unavailability: Any temporary server-side unavailability due to maintenance or availability constraints.
• Response: Return 503 Service Unavailable.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should retry with:
  • Base interval: 5000 ms
  • Exponential factor: 2
  • Max retries: 12

Error responses – (504 Gateway Timeout)

• General principle: For unexpected server-side timeouts, the CDA will return 504 Gateway Timeout. The pension provider or scheme should retry using the defined backoff.
• Scenarios: [applicable to all rreguri HTTP methods; POST, PATCH and DELETE]
  • Downstream timeout: Any temporary timeout when communicating with a downstream CDA service.
• Response: Return 504 Gateway Timeout.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should retry with:
  • Base interval: 5000 ms
  • Exponential factor: 2
  • Max retries: 12

Use case 4: Pension provider or scheme – get view data request

Relevant APIs

• view-data (GET)
• introspect (POST)
• perm (POST)

view-data API (GET)

The view-data API is hosted by pension providers or schemes and is used by dashboard providers to retrieve pension and illustration details linked to a registered PeI.

Hosted by: Pension providers or schemes.

Called by: Dashboard providers.

Success responses – (200 OK):

• General principle: When a dashboard provider calls the view-data endpoint, the pension provider returns 200 OK along with the view_data_token constructed.
• Scenarios:
  • View data token returned: The pension provider or scheme generates a valid view_data_token containing the view data for the pension identified by the supplied asset_guid. It should conform to the view_data_token_payload_v1.3.json schema defined in the published v2.0 data standards.
• Response: Return 200 OK.
• Issued by: Pension provider or scheme.
• Parameters returned:
  • View_data_token (body)

Error responses – (400 Bad Request):

• General principle: In the following scenarios, the pension provider should return 400 Bad Request. The dashboard provider should not retry these scenarios.
• Scenarios:
  • Missing or invalid ‘Scope’: ‘Scope’ is missing or does not contain ‘owner’ in the query parameter.
  • Missing or invalid ‘X-Request-ID': X-Request-ID is missing or invalid in the header.
• Response: Return 400 Bad Request for all scenarios above.
• Issued by: Pension provider or scheme.
• Retry behaviour: The dashboard provider should not retry in these scenarios.

Error responses – (401 Unauthorized)

• General principle: In the following scenarios, the pension provider should return 401 Unauthorized. The dashboard provider should not retry these scenarios.
• Scenarios:
  • Invalid RPT: An invalid RPT was used on the request.
• Response: Return 401 Unauthorized.
• Issued by: Pension provider or scheme.
• Retry behaviour: The dashboard provider should not retry in these scenarios.

Error responses – (403 Forbidden or 400 Bad Request):

• General principle: For mTLS-related errors where the client certificate is missing or invalid, the provider should return 403 Forbidden (preferred) or 400 Bad Request if 403 is not supported. If neither option is possible, use a transport-level error. The dashboard provider should not retry these scenarios.
• Scenarios:
  • Missing or invalid client certificate: The client certificate for the request is missing or invalid.
• Response: Return 403 Forbidden (preferred) or 400 Bad Request. If not supported, use a transport-level error, for example, “connection refused”.
• Issued by: Pension provider or scheme.
• Retry behaviour: The dashboard provider should not retry in this scenario.

Error responses – (404 Resource Not Found)

• General principle: For incorrect URLs or wrong HTTP methods, return 404 Resource Not Found. The dashboard provider should not retry these scenarios.
• Scenarios:
  • Incorrect URL: The URL is incorrect or the wrong HTTP method was used on the request.
  • Missing or invalid ‘asset_guid’ path parameter: The asset_guid in the request path is missing or invalid.
  • Missing, invalid, or not recognised PeI: The PeI in the request is missing, invalid, or not recognised by the pension provider.
• Response: Return 404 Resource Not Found.
• Issued by: Pension provider or scheme.
• Retry behaviour: The dashboard provider should not retry in these scenarios.

Error responses – (405 Method Not Allowed or 400 Bad Request):

• General principle: For method not allowed, the pension provider should return 405 Method Not Allowed (preferred) or 400 Bad Request if 405 is not supported. The dashboard provider should not retry these scenarios.
• Scenarios:
  • Wrong method used on submission: A dashboard provider invokes the view-data endpoint using an HTTP method that is not supported.
• Response: Return 405 Method Not Allowed (preferred) or 400 Bad Request.
• Issued by: Pension provider or scheme.
• Retry behaviour: The dashboard provider should not retry in this scenario.

Error responses – (415 Unsupported Media type or 400 Bad Request)

• General principle: For incorrect content type, return 415 Unsupported Media Type (preferred) or 400 Bad Request if 415 is not supported. The dashboard provider should not retry these scenarios.
• Scenarios:
  • Missing or invalid Content-Type: Content-Type header is missing or incorrect (for example, not application/json;charset=UTF-8).
• Response: Return 415 Unsupported Media Type (preferred) or 400 Bad Request.
• Issued by: Pension provider or scheme.
• Retry behaviour: The dashboard provider should not retry in this scenario.

Error responses – (429 Too Many Requests)

• General principle: For excessive requests, return 429 Too Many Requests. The dashboard provider should retry using backoff.
• Scenarios:
  • Too many requests: Too many requests made within a short period.
• Response: Return 429 Too Many Requests.
• Issued by: Pension provider or scheme.
• Retry behaviour: The dashboard provider should retry with:
  • Base interval: 5000 ms
  • Exponential factor: 2
  • Max retries: 3

Error responses – (502 Bad Gateway or 500 Internal Server Error)

• General principle: For API Gateway issues, the pension provider or scheme should return 502 Bad Gateway (preferred) or 500 Internal Server Error if 502 is not supported. The dashboard provider should retry using backoff.
• Scenarios:
  • Provider API Gateway down: API Gateway is unavailable.
• Response: Return 502 Bad Gateway (preferred) or 500 Internal Server Error.
• Issued by: Pension provider or scheme.
• Retry behaviour: The dashboard provider should retry with:
  • Base interval: 5000 ms
  • Exponential factor: 2
  • Max retries: 3

Error responses – (503 Service Unavailable or 500 Internal Server Error)

• General principle: For maintenance, the pension provider or scheme should return 503 Service Unavailable (preferred) or 500 Internal Server Error if 503 is not supported. The dashboard provider should retry using backoff.
• Scenarios:
  • Provider maintenance: Planned or unplanned maintenance.
• Response: Return 503 Service Unavailable (preferred) or 500 Internal Server Error.
• Issued by: Pension provider or scheme.
• Retry behaviour: The dashboard provider should retry with:
  • Base interval: 5000 ms
  • Exponential factor: 2
  • Max retries: 3

introspect API (POST)

This is an API hosted by the CDA and used by pension providers and schemes to verity that an RPT in a view-data request grants sufficient permission to access the requested data.

Hosted by: CDA.

Called by: Pension providers or schemes.

Success responses – (200 OK):

• General principle: When the CDA successfully validates the RPT provided by the pension provider or scheme, it returns 200 OK along with the introspection details needed to determine whether the view-data request is authorised to proceed.
• Scenarios:
  • Successful RPT introspection: The CDA receives a valid RPT and returns introspection data confirming the token and its permissions.
• Response: Return 200 OK.
• Issued by: CDA.
• Parameters returned:
  • active
  • token_type
  • exp
  • iss
  • permissions
  • permissions.resource_id
  • permissions.resource_scopes
  • permissions.exp

Error responses – (400 Bad Request):

• General principle: In the following scenarios, the CDA will return 400 Bad Request. The pension provider or scheme should not retry these scenarios but should return 500 Internal Server error to the dashboard.
• Scenarios:
  • Missing or invalid ‘X-Request-ID': X-Request-ID is missing or invalid in the header.
  • Missing or invalid Token RPT: The RPT token is missing or invalid in the header.
• Response: Return 400 Bad Request for all scenarios above.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should not retry in these scenarios.
• Pension provider’s or scheme’s response to the dashboard provider: Return 500 Internal Server Error to the dashboard provider to inform them of an issue server side.

Error responses – (401 Unauthorized)

• General principle: For unauthorized PAT used on the request, the CDA return 401 Unauthorized. The pension provider or scheme should not retry these scenarios.
• Scenarios:
  • Unauthorized PAT: An unauthorized PAT was used on the request.
  • Missing or invalid PAT: The PAT is missing or invalid, preventing the CDA from validating the request.
  • Expired PAT: The PAT provided in the request has expired, preventing the CDA from completing the PMT issuance process.
• Response: Return 401 Unauthorized.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should not retry in these scenarios.
• Pension provider’s or scheme’s response to the dashboard provider: Return 401 Unauthorised to the dashboard provider to inform them of the issue with the PAT.

Error responses – (500 Internal Server Error)

• General principle: For unexpected server-side failures, the CDA will return 500 Internal Server Error. The pension provider or scheme should retry using the defined backoff.
• Scenarios:
  • Unexpected server error: Any unexpected server-side failure occurs during processing.
• Response: Return 500 Internal Server Error.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should retry with:
  • Base interval: 5000 ms
  • Exponential factor: 2
  • Max retries: 3
• Pension provider’s or scheme’s response to the dashboard provider: If the retry limit is exceeded, return 500 Internal Server Error to the dashboard provider to inform them of an issue server side.

Error responses – (503 Service Unavailable)

• General principle: For unexpected server-side unavailability, the CDA will return 503 Service Unavailable. The pension provider or scheme should retry using the defined backoff.
• Scenarios:
  • Temporary server unavailability: Any temporary server-side unavailability due to maintenance or availability constraints.
• Response: Return 503 Service Unavailable.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should retry with:
  • Base interval: 5000 ms
  • Exponential factor: 2
  • Max retries: 3
• Pension provider’s or scheme’s response to the dashboard provider: If the retry limit is exceeded, return 500 Internal Server Error to the dashboard provider to inform them of an issue server side.

Error responses – (504 Gateway Timeout)

• General principle: For unexpected server-side timeouts, the CDA will return 504 Gateway Timeout. The pension provider or scheme should retry using the defined backoff.
• Scenarios:
  • Downstream timeout: Any temporary timeout when communicating with a downstream CDA service.
• Response: Return 504 Gateway Timeout.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should retry with:
  • Base interval: 5000 ms
  • Exponential factor: 2
  • Max retries: 3
• Pension provider’s or scheme’s response to the dashboard provider: If the retry limit is exceeded, return 500 Internal Server Error to the dashboard provider to inform them of an issue server side.

perm API (POST)

This perm API is hosted by the CDA and enables pension providers and schemes to retrieve permission tokens required by view-data clients to obtain the correct RPT for accessing requested data.

Hosted by: CDA.

Called by: Pension providers or schemes.

Success responses – (201 Created):

• General principle: When the CDA successfully creates a PMT for the pension provider or scheme, it returns a 201 Created along with the PMT ticket included in the response.
• Scenarios:
  • PMT successfully created: The CDA generates a PMT (as a JWT) in response to the permission request sent by the pension provider or scheme.
• Response: Return 201 Created.
• Issued by: CDA.
• Parameters returned:
  • ticket (body)

Error responses – (400 Bad Request):

• General principle: In the following scenarios, the CDA will return 400 Bad Request. The pension provider or scheme should not retry these scenarios but should return 500 Internal ServerError to the dashboard.
• Scenarios:
  • Missing or invalid ‘X-Request-ID': X-Request-ID is missing or invalid in the header.
  • Missing or invalid ‘resource_id’: The resource_id field in the request body is missing or invalid.
  • Incorrect resource_scopes values: The resource_scopes field is not set to the allowed values [“value”, “owner”].
• Response: Return 400 Bad Request for all scenarios above.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should not retry in these scenarios.
• Pension provider’s or scheme’s response to the dashboard provider: Return 500 Internal Server Error to the dashboard provider to inform them of an issue server side.

Error responses – (401 Unauthorized)

• General principle: In the following scenarios, the CDA will return 401 Unauthorized. The pension provider or scheme should not retry these scenarios but should return 401 Unauthorized error to the dashboard.
• Scenarios:
  • Missing or invalid PAT: The PAT is missing or invalid, preventing the CDA from validating the request.
• Response: Return 401 Unauthorized.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should not retry in these scenarios.
• Pension provider’s or scheme’s response to the dashboard provider: Return 401 Unauthorized to the dashboard provider to inform them of the issue with the PAT.

Error responses – (500 Internal Server Error)

• General principle: For unexpected server-side failures, the CDA will return 500 Internal Server Error. The pension provider or scheme should retry using the defined backoff.
• Scenarios:
  • Unexpected server error: Any unexpected server-side failure occurs during processing.
• Response: Return 500 Internal Server Error.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should retry with:
  • Base interval: 5000 ms
  • Exponential factor: 2
  • Max retries: 3
• Pension provider’s or scheme’s response to the dashboard provider: If the retry limit is exceeded, return 500 Internal Server Error to the dashboard provider to inform them of an issue server side.

Error responses – (503 Service Unavailable)

• General principle: For unexpected server-side unavailability, the CDA will return 503 Service Unavailable. The pension provider or scheme should retry using the defined backoff.
• Scenarios:
  • Temporary server unavailability: Any temporary server-side unavailability due to maintenance or availability constraints.
• Response: Return 503 Service Unavailable.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should retry with:
  • Base interval: 5000 ms
  • Exponential factor: 2
  • Max retries: 3
• Pension provider’s or scheme’s response to the dashboard provider: If the retry limit is exceeded, return 500 Internal Server Error to the dashboard provider to inform them of an issue server side.

Error responses – (504 Gateway Timeout)

• General principle: For unexpected server-side timeouts, the CDA will return 504 Gateway Timeout. The pension provider or scheme should retry using the defined backoff.
• Scenarios:
  • Downstream timeout: Any temporary timeout when communicating with a downstream CDA service.
• Response: Return 504 Gateway Timeout.
• Issued by: CDA.
• Retry behaviour: The pension provider or scheme should retry with:
  • Base interval: 5000 ms
  • Exponential factor: 2
  • Max retries: 3
• Pension provider’s or scheme’s response to the dashboard provider: If the retry limit is exceeded, return 500 Internal Server Error to the dashboard provider to inform them of an issue server side.