Error Objects

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:

string

required

A human-readable error message describing what went wrong. This provides a high-level summary of the error.

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 Code	Description
`400`	Bad Request - The request was invalid or cannot be processed. Check the error message for details about what needs to be corrected.
`401`	Unauthorized - Authentication failed or was not provided. Ensure you have a valid access token and proper credentials.
`403`	Forbidden - The authenticated user does not have permission to access the requested resource.
`404`	Not Found - The requested resource could not be found.
`500`	Internal 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.

API documentation

Authentication

Employee Data

Employee Updates

Employer Identifiers

Invites

Meta

Pay Categories

Payroll Connections

Payroll Platforms

Payroll Records

Users

Overview

Error Object Structure

Example Error Response

Common HTTP Status Codes

​Overview

​Error Object Structure

​Example Error Response

​Common HTTP Status Codes

Overview

Error Object Structure

Example Error Response

Common HTTP Status Codes