Errors

Starting from version 2023-02-01, error messages will have consistent JSON structures. The shape may differ between the error types. Below are the 4 error types with examples of their shape.

Basic Error Shape

All errors start with the basic error shape and can be expanded upon.

When a request results in an error, the response JSON contains an array of errors with the following fields
error_key: specifies where the error occurs. Typically this key identifies the attribute/parameter related to the error. In the example below, the error is a request error.
category: specifies the type of error. The category provides error groupings and can be used to build custom error handling in your integration. For a complete list of all error categories please review the error categories guide.
message : provides details about the error. Except for a few types of errors, the message can be surfaced directly to the end user.
metadata: contains relevant data to identify the resource in question when applicable. In the majority of cases, entity_uuid and entity_type will be provided, but the data may change based on the domain of the endpoint.

{
  "errors": [
    {
      "error_key": "base",
      "category": "payroll_blocker",
      "message": "Company or employee address could not be verified. Please ensure all addresses are valid.",
      "metadata": {
        "key": "geocode_error"
      }
    }
  ]
}

Resource Error Shape

When working with a specific resource (employee, company, payroll, etc), multiple errors can be returned.

{
  "errors": [
    {
      "error_key": "first_name",
      "category": "invalid_attribute_value",
      "message": "First name is required"
    },
    {
      "error_key": "date_of_birth",
      "category": "invalid_attribute_value",
      "message": "Date of birth is not a valid date"
    }
  ]
}

Nested Error Shape

When the error attribute is nested inside a parent attribute, the errors are nested inside a wrapping error with “nested_error” category. Use the category (nested_error) to programmatically identify and parse nested errors.

{
  "errors": [
    {
      "error_key": "fields",
      "category": "nested_errors",
      "errors": [
        {
          "error_key": "signature",
          "category": "invalid_attribute_value",
          "message": "Field is required."
        },
        {
          "error_key": "phone",
          "category": "invalid_attribute_value",
          "message": "Field is required."
        }
      ]
    }
  ]
}

Batch Error Shape

Some endpoints perform bulk operations on multiple resources. If one of these endpoints has an error, the response is an array of resource errors. The metadata can be used to help identify the entities associated with the errors.

{
  "errors": [
    {
      "error_key": "base",
      "category": "invalid_attribute_value",
      "message": "Hours accrued this year (50.0) must be less than or equal to max accrual hours per year (25.0)",
      "metadata": {
        "entity_uuid": "387a183a-db93-45d3-a1b3-028dbea82af3",
        "entity_type": "Employee"
      }
    },
    {
      "error_key": "base",
      "category": "invalid_attribute_value",
      "message": "Balance must be less than or equal to max balance (100.0)",
      "metadata": {
        "entity_uuid": "693ada8e-7b24-4a19-a252-240637a553eb",
        "entity_type": "Employee"
      }
    }
  ]
}