Error Responses

Example of a Standard Validation\Logic Error Message

The following is an example of a response from the Payroll API reflecting a validation or logic error. The response will be a BadRequest: HttpCode 400 (unless there is a Conflict: HttpCode 409). The response includes a list of apiErrors (although usually only one apiError is returned). Each apiError includes an error code along with an errorHint. The errorHint describes the issue in a straightforward language.

BaseApiResponse
{
  "isSuccess": true,
  "apiErrors": [
    {
      "errorCode": "USERHASNOACCESSTOEMPLOYER",
      "errorHint": "The user account you are connecting with does not have access to the Employer."
    }
  ]
}

Suggested error message to display to the User

Your request has failed. The Bright system has returned the error message: The user account you are connecting with does not have access to the Employer.

Example of an Unrecoverable Error Message

If the Payroll API has an unrecoverable\exception error then it will return a message as below. This response will be a BadRequest (HttpCode 400). Note the errorId value can help the support team to determine the issue and so should be displayed to the user.

BaseApiResponse
{
  "isSuccess": true,
  "apiErrors": [
    {
      "errorCode": "UNKNOWNERROR",
      "errorId": "83ce3515-f1b2-48f0-95de-6d0d325efc12",
      "errorHint": "An error has occurred. Please try again later. If the issue persists please contact support with your Error Id."
    }
  ]
}

Suggested error message to display to the User

Your request has failed. The Bright system has returned the error message(s)

An error has occurred. Please try again later. If the issue persists please contact support with your Error Id. Error id: 83ce3515-f1b2-48f0-95de-6d0d325efc12

End Of Financial Year

BrightPay provides different applications for each financial year. Around the beginning of the financial year (both just before and just after) the Payroll API may be unsure of which year\application to get data from or which year to load data into. For more information, please see End Of Year Behaviour.

Therefore, around the turn of the financial year the Payroll API may try to perform an action on both financial years, possibly leading to two error messages.

End Of Financial Year: Errors Retrieving Data

For this reason when trying to retrieve data via the Payroll API (around the change of the financial year) the Payroll API will attempt to contact the BrightPay application for the previous and next financial year. As long as the Payroll API gets data from one BrightPay application it will return a success message. If requests to both applications fail then the API will likely return multiple apiErrors (one for each year).

BaseApiResponse
{
  "isSuccess": true,
  "apiErrors": [
    {
      "errorCode": "USERHASNOACCESSTOEMPLOYER",
      "financialYear": "24/25"
      "errorHint": "The user account you are connecting with does not have access to the Employer."
    },{
      "errorCode": "USERHASNOACCESSTOEMPLOYER",
      "financialYear": "25/26"
      "errorHint": "The user account you are connecting with does not have access to the Employer."
    }
  ]
}

Suggested error message to display to the User

Your request has failed. The Bright system has returned the error message(s)

Financial year 24/25: The user account you are connecting with does not have access to the Employer.

Financial year 25/26: The user account you are connecting with does not have access to the Employer.

End Of Financial Year: Errors Uploading Data

When uploading data there is more chance of validation issues (in both years) as the logic and validation is more complex. An example error message is shown below:

BaseApiResponse
{
  "isSuccess": true,
  "apiErrors": [
    {
      "errorCode": "PAYPERIODNOTFOUND",
      "financialYear": "24/25"
      "errorHint": "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."
    },{
      "errorCode": "NOTCURRENTPAYSLIP",
      "financialYear": "25/26"
      "errorHint": "The payslip connected to the dates you have supplied is not the current payslip, only the current open payslip can have payments added to it. Please fix the issues in BrightPay (such as finalising the previous payslip) or 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."
    }
  ]
}

Suggested error message to display to the User

If displaying an error message to the User it is best to display the year and error hint.

Your request has failed. The Bright system has returned the error message(s)

Financial year 24/25: 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.

Financial year 25/26: The payslip connected to the dates you have supplied is not the current payslip, only the current open payslip can have payments added to it. Please fix the issues in BrightPay (such as finalising the previous payslip) or 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.