Error Code Definitions

The following error codes may be returned from the API along with a hint for the user.

BadRequest General Error Codes

These are error codes that may be returned by any request (as BadRequest: HttpCode 400)

Code	Error Hint Supplied By API	Notes
UNKNOWNERROR	An error has occurred but there is no error code to report. Please try again later.	An internal error has occurred, the errorId field should be populated in case the user needs to contact support.
PARTOFSYSTEMDOWN	Part of the system is currently down and therefore the request cannot be completed. Please try again later.	An internal API that the process depends on is likely down, user could try again later.
ERRORCODEUNDEFINED	An error has occurred but there is no error code to report. Please try again later.	An internal API has returned an unrecognised code, user could try again later.
NOPERMISSONTOORGANISATION	The user account that you are connecting with does not have the correct permissions to access the Organisation.	If your integration retrieves the Organisation\Employer at the start of the process this scenario is unlikely to occur.
EMPLOYERDOESNOTEXISTORNOTCONNECTEDTOORGANISATION	The employerId supplied does not exist or is not connected to the organisationId supplied.	If your integration retrieves the Organisation\Employer at the start of the process this scenario is unlikely to occur (unless near the end of the financial year).
INCORRECTPERMISSONSFOREMPLOYER	The user account you are connecting with does not have the correct permissions to access the Employer.	If your integration retrieves the Organisation\Employer at the start of the process this scenario is unlikely to occur (unless near the end of the financial year).
USERHASNOACCESSTOEMPLOYER	The user account you are connecting with does not have access to the Employer.	If your integration retrieves the Organisation\Employer at the start of the process this scenario is unlikely to occur (unless near the end of the financial year).
CONFLICT	Someone else has updated one of the records you are trying to change, please try again.	Issue with multiple people\applications updating the same data, user could try again later.
NOORGANISATIONSAVAILABLE	There are no organisations available. Either none are set up or there is an outstanding bill.	There are no unexpired Organisation available. Either no Organisation have been set up or there is an outstanding bill.
ORGANISATIONIDISEMPTY	The request contains a blank Organisation Id, please try again and if the issue persists contact the technical support of your supplier.	There is likely an issue with the integration code as the Organisation Id is being passed as an empty Guid (00000000-0000-0000-0000-000000000000)
EMPLOYERIDISEMPTY	The request contains a blank Employer Id, please try again and if the issue persists contact the technical support of your supplier.	There is likely an issue with the integration code as the Employer Id is being passed as an empty Guid (00000000-0000-0000-0000-000000000000)

Conflict General Error Code

Below is the Conflict error code that may be returned by any request (as Conflict: HttpCode 409).

Code	Error Hint Supplied By API	Notes
CONFLICT	Someone else has updated one of the records you are trying to change, please try again.	Issue with multiple people\applications updating the same data, user could try again later.

Error Codes related to Specific Payroll API Functions

Some error codes are connected to individual Payroll API functions.

Payroll API V1.0: Errors connected to the function "Create Employee Hourly Payments"

The error codes below may be returned by the method Create Employee Hourly Payments.

Code	Error Hint Returned By API	Notes
EMPLOYERHASNOEMPLOYEES	The Employer does not have any Employees set up. Please check you are using the correct EmployerId or alternatively please use BrightPay to set up Employees.	Configuration issue that needs resolved in BrightPay.
EMPLOYEENOTFOUND	The employee has not been found. Please check you are using the correct EmployeeId.	Should not happen if Employees are pulled on each integration, potentially a design flaw in the integration.
HOURLYPAYMENTSMISSING	The request to create hourly payments has an error. The request is missing a list of Hourly Payments or the list is empty. For the request to be accepted at least one Hourly Payment must be supplied.	The HourlyPayment list must have at least one record. Potentially a design flaw in the integration.
HOURLYPAYMENTSERROR	The request to create hourly payments has an error. One of the hourly payments is missing or the payment rate is missing.	This is a design flaw in the integration, either a null object has been passed as an HourlyPayment or a HourlyRate field is set to null or an empty string.
HOURLYPAYMENTSMULTIPLIERERROR	The request to create hourly payments has an error. An hourly payment which has an hourly rate field set to a value other than the "Standard rate" has a multiplier set to a value other than 1.0. Only hourly payments with an Hourly Rate field set to "Standard rate" can have a multiplier other than 1.0.	This is a design flaw in the integration, an hourly rate which is not set to "Standard rate" has a multiplier set to a value other than 1.0 (which is not permitted).
PAYPERIODNOTFOUND	The request to create hourly payments likely has an error. There is no pay period or payslip available for the dates supplied please check the request is passing correct values.	Potentially an issue with the date supplied being outside the financial years supported by the API.
NOTCURRENTPAYSLIP	The payslip connected to the dates you have supplied is not the employee’s current payslip, only the current open payslip can have payments added to it. Please try and fix the issue in BrightPay (for example finalising the previous payslip or checking the employee start or finish date). Alternatively adjust the data you are submitting. Note the earliest date supplied in the request was 22/04/24 which identified a payslip with dates between 21/04/24 and 27/04/24 inclusively.	Potentially a BrightPay configuration issue or a data issue (the wrong date has been specified in the data)
HOURLYPAYMENTOUTSIDEOPENPAYSLIP	Payments can only be loaded into the Employee's current open payslip. The system was able to find the Employee's current open payslip however at least one hourly payment provided was after the end date of the payslip, please adjust the data you are submitting and try again. Note the earliest date supplied in the request was 22/04/24 which identified a payslip with dates between 21/04/24 and 27/04/24 inclusively.	This is likely to be a data issue, as the payments proposed are straddling two payslip periods.
PAYRATENOTRECOGNISED	The request to create hourly payments has an error. One of the Pay Rates supplied is not found in the system. The unrecognised Hourly Rate(s) are -MY INCORRECT PAYRATE-	This is likely to be a data issue or the API is working across multiple years and the data is not recognised.
TOOMANYHOURLYPAYMENTLINESONPAYSLIP	The request to create hourly payments has failed as there would be too many hourly payment lines on the payslip. Please use BrightPay to check the payslip is correct as it is likely that something is wrong.	There is a limit to the amount of hourly lines on a payslip (set to a high level). The number of hourly lines on the payslip is calculated by adding the existing hourly lines on the payslip plus the proposed hourly lines. Either the payslip has many hourly lines to start with or the data supplied is proposing adding too many lines. The limit is set to a high practical level and so this issue should not occur unless something has gone wrong.
EMPLOYEENOTASSIGNEDSCHEDULE	The employee has not been assigned a "Payment Schedule" and therefore does not have any open payslips. Please open the Employee in BrightPay and assign them a "Payment Schedule" under the "Payment" tab.	There is an issue with the Employee's configuration in BrightPay.
HOURLYPAYMENTSMULTIPLIERZEROORNEGATIVEERROR	The request to create hourly payments has an error. At least one multiplier is either zero or a negative value, multipliers must be positive values.	The request should have multipliers that are positive values. Potentially a design flaw in the integration.
HOURLYPAYMENTSHOURSNEGATIVEERROR	The request to create hourly payments has an error. At least one of the hours worked values is a negative value, the hours worked values must be zero or a positive value.	The request should have hours worked that are zero or positive values. Potentially a design flaw in the integration.
NOORGANISATIONSAVAILABLE	There appears to be no organisations in BrightPay connected to your account. Please check that you are using the correct account to connect to BrightPay or that your subscription has not expired.	The wrong account is being used or there is an issue with the subscription.