Timeouts on Production

API Platform
1

In our production environment, we’ve been experiencing timeouts when making requests with grant_type=refresh_token to the URL: https://api.service.nhs.uk/oauth2/token. Currently, the timeout is hardcoded to 5 seconds. Is there a recommended or maximum timeout limit that should be configured for this endpoint? We are using CIS2- refresh token calls, when refreshing access token we are getting timeouts-

2

Hi Niru,

A 5-second hardcoded timeout is on the low side for production environments — especially if your calls traverse enterprise networks or HSCN, where occasional latency spikes can occur.

We recommend setting client timeouts to at least 15–30 seconds for token requests, with retry logic using exponential backoff if a timeout does occur. This aligns with best practice for CIS2 refresh token flows, ensuring resiliency if there is transient load or network latency.

Hope the above help.

Thanks,

NHS England API Platform team

Please note: The API Platform team can only address queries relevant to the NHS England API platform, including security, rate limiting, logging, monitoring and alerting. For any API specific queries, please reach out the relevant API teams.

3

Thanks Navin

Our messages are failing with the following error. Could you help us identify the root cause? Understanding this will help us investigate where things are going wrong. We understand refresh_token being wrong - But in this case, what is expected and what is sent would be helpful

HTTP operation failed invoking https://api.service.nhs.uk/oauth2/token with statusCode: 401 { “error”: “invalid_grant”, “error_description”: “refresh_token is invalid”, “message_id”: “rrt-7130427900976519152-c-geu2-2278193-102922341-4” }

4

Hi Niru,

The refresh_token is invalid error could be due to any of the following:

  • Refresh token may have expired as they have a finite lifetime and must be rotated.
  • Refresh tokens are single-use only. Once you have exchanged it for a new access token, you must use the new refresh token returned in that response for subsequent calls.
  • Ensure that the refresh token you are submitting was issued by the same environment (PROD vs INT).
  • Token audience mismatch - check the aud claim in the original JWT; the refresh token must correspond to the same token endpoint you’re calling.

In short, always store and use the latest refresh token returned by the API Platform; old ones will be rejected.

  • We recommend configuring a client timeout of at least 30 seconds for token calls in PROD. This aligns with NHS platform guidance and avoids premature termination of requests on your side.

If you are consistently seeing responses exceeding 30s, please raise a ticket via : Customer Service Portal - Customer Support with Client ID, timestamps etc. so we can check server-side logs.

Thanks,

NHS England API Platform team

Please note: The API Platform team can only address queries relevant to the NHS England API platform, including security, rate limiting, logging, monitoring and alerting. For any API specific queries, please reach out the relevant API teams.