GuidesReferenceChangelogAPI Upgrades
Reference
Start typing to search…

Errors

Check uses standard HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate client errors, and codes in the 5xx range indicate a server error that we will immediately work to fix. All Check errors conform to the following schema:

Attribute

Description

type string

Type of the error.

message
string

Description of the error and how to fix it.

input_errors
list

Optional. Array of input error objects. Each input error object contains field, field_path, and message string attributes.

For example, the following JSON error will be returned when attempting to update a Payroll resource with a nested payroll item that's missing an employee field:

{
  "error": {
    "type": "validation_error",
    "message": "Please correct the required fields and try again.",
    "input_errors": [
      {
        "message": "This field is required.",
        "field": "employee",
        "field_path": ["items", "0", "employee"]
      }
    ]
  }
}

Each error in input_errors conform to the following schema:

Attribute

Description

type
string

Human-readable error message.

field
string

Name of the field (or non_field_errors).

field_path
array

List-based path pointing to the invalid field or object.

🔍 What is field_path?

The field_path is a list of keys and/or list indices that shows exactly where in your input the validation error occurred.

✅ Example

["items", "6", "earnings", "0", "hours"]

Equivalent in Python:

payload["items"][6]["earnings"][0]["hours"]

Note: All segments are strings in the JSON response, but numeric indices refer to list positions.

⚙️ How to Traverse field_path

def get_value_at_path(data, path):
    current = data
    for segment in path:
        if isinstance(current, list):
            segment = int(segment)
        current = current[segment]
    return current

🔁 Grouping Errors by Item

If you want to show errors grouped by payroll item:

from collections import defaultdict
def group_errors_by_item(errors):
    grouped = defaultdict(list)
    for err in errors:
        path = err["field_path"]
        if path and path[0] == "items":
            grouped[path[1]].append(err)
    return grouped

❗ What Are non_field_errors?

non_field_errors are used when the error is not related to a specific field — often due to:

  • Cross-field validation
  • Business rules

✅ Example

{
  "error": {
    "type": "validation_error",
    "message": "Please correct the required fields and try again.",
    "input_errors": [
      {
        "field": "non_field_errors",
        "field_path": [
          "items",
          "56",
          "post_tax_deductions",
          "non_field_errors"
        ],
        "message": "Cannot approve payroll pay_123 since one or more post-tax deductions have negative amounts causing negative quarter-to-date amounts: ptd_456, ptd_789. Please correct these negative amounts before re-approving."
      }
    ]
  }
}

🧭 How to Handle non_field_errors

  • Use field_path to locate the object (e.g., post_tax_deductions) in your input.
  • Treat the error as a general issue on the object, not a specific field.
  • Display it as a form-level or block-level error in UI.