Troubleshooting 5xx status codes

Cause
A generic error occurred on the server, and it could not handle the request properly.

Steps

1. Retry the request after a short delay to see if the issue is transient.
2. Check the API’s status page or known issues board (if available) to see if there is an ongoing incident.
3. Inspect your request payload and headers to confirm there is no hidden client-side error.

Fix

• if the issue persists, contact NHS England API support with details (request logs and timestamps etc.)
• implement general retry logic in your code to handle unexpected server issues

Cause
The server either does not recognise or support the request method, which it cannot handle. (The only methods that servers are required to support are GET and HEAD.)

Steps

1. Confirm the HTTP method (GET, POST, PUT, PATCH, DELETE) is one that the API actually supports.
2. Review the API specification to ensure you are using the correct operation.

Fix

Change the request method to a supported method. In rare cases where the server truly does not support a feature, you may need to contact the API team for clarification or future support.

Cause
The server, acting as a gateway or proxy, got an invalid response from an upstream server.

Steps

1. Retry the request, as 502 errors are often transient.
2. Check if there are any network issues between your system and the API gateway.

Fix

Wait briefly, then retry. If the error persists, check for official service announcements or contact support.

Cause
The server is currently overloaded or down for maintenance.

Steps

1. Confirm whether there is scheduled maintenance or a known service outage.
2. Check your application logs for the timing of repeated 503 errors.

Fix

• use exponential backoff for retries
• monitor the service status page or contact support to see when the service is back online

Cause
The server, acting as a gateway or proxy, did not receive a timely response from an upstream server.

Steps

1. Retry the request after a short interval.
2. Investigate whether the endpoint is experiencing performance issues and if a large or complex request is timing out.

Fix

• optimise your request (for example, reduce payload size if possible)
• if the request is time-sensitive or cannot be reduced, contact the API team to discuss possible timeout configurations or performance constraints