Follow this guide to handle pay run errors and exceptions. There are three sections to this guide, which you must follow carefully in order:
- Check the logs to identify the error and use the exception matrix
- Usually, you will then handle the report submission exception, but not always
- Handle the Pay run exception
1. Check the logs #
You must check the status, severity and logs of the pay run and report submissions.
Pay run log #
Go to Pay runs and note the Status/Severity of the Pay run, usually ERROR:
Next, click View next to the Pay run to establish the cause of the exception.
Click the Logs tab and look for any ERROR which may be on the Next screen control at the bottom of the page:
Report log(s) #
Click the Pay run Reports tab:
- View each report with an ERROR status/severity
- Scroll down to see the details
- Click on the Logs tab
Exception lookup matrix #
Once you have this information, carefully match the row on the table below which applies to your situation. Then follow the steps depending on whether you have an Unapproved/ Approved Pay Run:
| Report Submission State/ Severity and Logs | Pay run Status/Severity and Logs | Explanation of what happened | Unapproved Pay run -Steps to handle the exception | Approved Pay run – Step(s) to handle the exception |
|---|---|---|---|---|
| All reports DONE | ERROR: RuntimeError: Waited more than 300s for reports | The pay run workflow stopped waiting after 300 seconds (5 minutes); sometime after that, the FPS and/or EPS reports were completed successfully. | Redo | 3a Resume report submissions (any issues have been resolved). |
| FPS/EPS ERROR: FPS and/or EPS exceeded 40 retries | ERROR: RuntimeError: Waited more than 300s for reports | HMRC did not respond after 40 attempts, and the report submissions were never completed. | Redo | – Wait a short period. – 2.1 Continue the submission; if that fails, 2.2 Restart the submission. – 3a. Resume report submissions (any issues have been resolved). |
| FPS/EPS ERROR: The supplied user credentials failed validation for the requested service. (1046) | ERROR: Reports taking too long | The HMRC server is experiencing a problem in looking up credentials if the Pay run is either: – Not approved – Approved, and you are certain that the FPS and/or EPS credentials are correct | – Wait a short while – Redo | – Wait for a short period. – 2.1 Continue the submission; if that fails, 2.2 Restart the submission. – 3a. Resume report submissions (any issues have been resolved). |
| FPS ERROR: FPS The submission of this document has failed due to departmental specific business logic in the Body tag. (3001) | ERROR: Reports taking too long | You must correct the report Submission error in your Pay run. Note that HMRC reports many types of errors. | – Correct the error – Redo | – 3b. Disapprove the payrun so updates can be made (invalidates existing submissions). – Correct the error – Approve |
| FPS/EPS ERROR: The supplied user credentials failed validation for the requested service. (1046) | ERROR: Reports taking too long | The FPS and/or EPS credentials are incorrect. | N/A | – 2.3. Reload settings. – 3a. Resume report submissions (any issues have been resolved). |
| GB Xero ERROR: RuntimeError: Token refresh_token error Bad Request (400). Xero API in ERROR state | ERROR: RuntimeError: Waited more than 300s for reports | The Xero token has expired and needs to be refreshed. | N/A | – Refresh the Xero token. – 2.3. Reload settings – 3a Resume report submissions (any issues have been resolved). |
| GB NEST Enrol and Contribute ERROR: ServerError | Sorry we are unable to process this request. This is because either your NEST online account is locked or you haven’t yet activated your NEST online account. p | – | – Unlock your account by using the ‘Unlock my account’ link on the Login page on NEST’s website. – Redo | – 2.2 Restart the submission. – 3a. Resume report submissions (any issues have been resolved). | |
| GB NEST Enrol and Contribute ERROR: RuntimeError: No usable groups. Hint: is schedule available? You’ve already submitted contributions for the member in this schedule. (IFC01681) | ERROR: Reports taking too long | NEST generated an error. Because the FPS and EPS submissions were successful, you should manually update NEST. | – Correct the NEST scheme – Redo | – 2.4. End the report submission. – 3a. Resume report submissions (any issues have been resolved). – Download/Upload NEST files from Documents if required |
| GB Revolut ERROR: ServerError: GB Revolut unexpected retry response: Report submission#582883.GB Revolut exceeded 20 retries | ERROR: Reports taking too long | The Revolut banking service did not respond after 20 retries | N/A | – Wait for a short period. – 2.1 Continue the submission; if that fails, 2.2 Restart the submission. – 3a. Resume report submissions (any issues have been resolved). |
Now, follow the appropriate sections, 2 or 3 below.
2. Report errors #
You must first handle the report submission errors/exceptions in most cases.
- Go to My tasks
- If you are a bureau and have many companies, Search for the company
- The Exception may be in Assigned tasks or Queued tasks, depending on how many administrators you have
- Carefully identify the report that is failing
- Then click Handle Exception as Master Admin (you may need to repeat for multiple reports):
If there are multiple administrators, you may see a screen where you need to assign the Task to you by clicking Done:
Depending upon the type of error, choose one of the options below:
2.1. Continue the submission #
The first option to try in all cases is the default option to Continue the report submission as below:
2.2. Restart the submission #
If the above step fails, usually very quickly, then you will need to restart the submission. Change the Restart option below to Restart the report submission. This allows the entire report to be re-submitted from the start:
2.3. Reload settings #
In some cases, report settings need to be changed and then reloaded. These include:
Token refresh_token error Bad Request (400) {"error":"invalid_grant"} from https://identity.xero.com/connect/token Incorrect RTI credentials.Ensure the token has been refreshed.
After assigning the task, you will need to change Reload settings to Use new settings from the report definition instead of the settings from the pay run and Restart the report submission
2.4. End the report submission #
If you are sure that you want to end the report submission, choose this option. Typically, this is because:
- You have an alternative method to submit a report, e.g. CSV
- You need to redo the pay run
Check that the report has been completed successfully.
After handling a report submission exception, you must handle the pay run exception.
Note: The original error log is retained in this scenario and will show in the pay run listing, but it is no cause for concern.3. Pay run errors #
You must handle the pay run exception once you have resolved any report submission exceptions. Below are two paths to follow, depending upon whether the pay run was correct and can continue (more common), or whether you need to disapprove the pay run and make changes (less common).
- Go to My tasks and locate the pay run that is failing
- If you are a bureau and have many companies, Search for the company
- The Exception may be in Assigned tasks or Queued tasks, depending on how many administrators you have
- Then click Resume Submission as Payroll Approver:
If there are multiple administrators, you may see a screen where you need to assign the Task to you by clicking Done:
3a. Resume report submissions (any issues have been resolved) #
For report submissions that have completed successfully, the usual step is to select Yes; Resume report submissions (any issues have been resolved) and click Done. The Pay run workflow will then continue.
3b. Disapprove the payrun so updates can be made (invalidates existing submissions) #
If you discover that the cause of a report submission exception needs to be corrected in the pay run, you should select: No: Disapprove the payrun so updates can be made (invalidates existing submissions) and click Done. This puts you back in a position to make any required changes:
Make any required changes and proceed to approval.