Troubleshooting 4xx status codes

Cause
A required parameter is invalid (for example, an access token is invalid). Ensure the header parameter is valid and conforms to your API's endpoint specification.

Steps

1. Compare the header parameters in your request against the API documentation.
2. Check that the header content (for example, the token format) matches what the API specification expects.
3. Confirm the request syntax (URL, body payload, etc.) and verify there are no typos or formatting issues.

Fix

Correct any incorrect parameters or values so they conform exactly to the API specification.

If you suspect an expired or invalid token, obtain a new token and retry. 

Cause
A required parameter (for example, the access token) is missing entirely. Ensure the header parameter is populated and conforms to your API's endpoint specification.

Steps

1. Inspect the headers in your request to identify any missing required fields.
2. Cross-check against the API documentation to confirm all mandatory headers are present.

Fix

• add the missing header parameter in the correct format
• ensure any environment variables (if used) are correctly set and not empty

Cause
Authorisation credentials are not valid (for example, a wrong token or invalid client ID/secret). Ensure you follow the instructions in the appropriate security pattern for your API's access mode.

Steps

1. Ensure you are using the correct security pattern for your API’s access mode (OAuth2, app-based auth, etc.).
2. Double-check that the credentials (token, keys) have not expired or been revoked.
3. Confirm you are pointing to the correct environment (sandbox vs. production).

Fix

• update or refresh your tokens/credentials
• use the correct client ID and secret or the correct authorisation flow as outlined in the API’s security documentation

Cause
Authorisation credentials are missing or not valid in request. Ensure you follow the instructions in the appropriate security pattern for your API's access mode.

Steps

1. Check the request headers to confirm an authorisation header is included.
2. Verify your method of sending credentials (Bearer token, basic auth header, etc.) is correctly implemented.

Fix

• supply the required credentials, typically via an authorisation: Bearer <token> header or other pattern used by the API
• re-test to confirm the credentials are included in every request

Cause
You have valid credentials, but do not have permission to perform the requested action. Ensure you follow the instructions in the appropriate security pattern for your API's access mode.

Steps

1. Check if your credentials or user role is restricted from accessing this particular endpoint or resource.
2. Review the API documentation or contact an administrator to see if additional scopes or roles are needed.

Fix

• request the necessary permissions or roles from the API provider
• update any OAuth2 scopes or client configurations if required

Cause
Similar to the above, the user or application is not permitted to carry out the specific action or operation. Ensure you follow the instructions in the appropriate security pattern for your API's access mode.

Steps

1. Confirm the endpoint you are calling is actually accessible to your user/app role.
2. Look for any custom policy or rule that might be blocking this request.

Fix

• obtain higher-level privileges or the correct role assignment
• check any policy or firewall rules that might be preventing access to that endpoint

Cause
The requested resource does not exist or cannot be found.

Steps

1. Verify the endpoint URL is correct (including path parameters or query strings).
2. Check whether the resource actually exists; if it’s a patient record or prescription, confirm you have the correct ID or reference.

Fix

Correct the URL, resource ID, or parameters in the request, Ensure the resource is present, and you have permission to view it.

Cause
There is a conflict with the current state of the resource, such as a task ID or prescription ID that already exists. For example, the request contains a task id and prescription id identical to a record already in the data store.

Steps

1. Ensure you are not creating a duplicate record or reusing a unique ID that has already been used.
2. Check if you must first delete or update an existing record before creating a new one.

Fix

Use a unique ID or follow the correct workflow to update existing resources. Handle concurrency by checking the current state of the resource before making changes.

Cause
Your application has exceeded the allotted rate limit.

Steps

1. Review the rate limits specified in the API documentation.
2. Monitor your requests to ensure you are not sending more than the permitted threshold within a given time window.

Fix

Implement backoff or retry logic, spacing out requests to stay within the limit. Where applicable, request a higher rate limit from the API provider, or optimise your calls to reduce frequency.