Skip to main content

​
Overview

When a request to the Payroll Integrations API fails, the response will include an error object with details about what went wrong. All error responses follow a consistent structure to make error handling straightforward and predictable.

​
Error Object Structure

Error responses contain the following fields:
​
message
string
required
A human-readable error message describing what went wrong. This provides a high-level summary of the error.
​
errors
array
An optional array of detailed error messages. When present, this provides additional context or lists multiple validation errors that occurred.

​
Example Error Response

Here’s an example of a typical error response: 
{
    "message": "Invalid request parameters",
    "errors": [
        "Field 'email' is required",
        "Field 'employerIdentifierId' must be a valid UUID"
    ]
}

​
Common HTTP Status Codes

The API uses standard HTTP status codes to indicate the type of error:
Status CodeDescription
400Bad Request - The request was invalid or cannot be processed. Check the error message for details about what needs to be corrected.
401Unauthorized - Authentication failed or was not provided. Ensure you have a valid access token and proper credentials.
403Forbidden - The authenticated user does not have permission to access the requested resource.
404Not Found - The requested resource could not be found.
500Internal Server Error - An unexpected error occurred on the server. If this persists, contact support.
Important: Error messages are not guaranteed to remain consistent between API versions.Do not write code that depends on exact error message text, as these messages may change without notice to improve clarity or provide better context. Instead, rely on HTTP status codes and structure your error handling logic accordingly.