validation_error (422)

← Error reference

validation_error

HTTP status: 422

Retryable: No. Retrying without changes will fail the same way.

The request body or query parameters failed schema validation.

When it fires

A schema rejected an applicant or session resource request. These request bodies use snake_case (`family_name`, `given_names`, `date_of_birth`, `postal_code`, `place_id`), so a camelCase or mis-typed field is not a recognized property (workflow-template configuration fields, such as step `config`, stay camelCase and are not affected). The create and patch requests (`POST /v1/applicants`, `POST /v1/sessions`, `PATCH /v1/applicants/{id}`) reject an unknown or mis-cased field with a 422 rather than silently dropping it, so a typo can no longer be lost without notice. The `details.issues` array holds every problem; when an unknown field is close to a real one, its `message` names it and suggests the intended key, for example `Unknown field "familyName". Did you mean "family_name"?`. A field that was removed from the wire instead gets its replacement, and the shape of that replacement, spelled out in the same `message`. The applicant name fields are the most common source of this error: `family_name` with the ordered `given_names` array replaced `first_name` / `middle_name` / `last_name`, and it is also what to send in place of `legal_name` or `full_name`, because no request body accepts a whole undivided name (`legal_name` is still returned on the applicant response, where it is read-only). When one property fails a value rule instead, `param` names it.

How to handle it

Read `details.issues` (and `param` when present) to fix the input. For an `Unknown field` issue, rename the field to the suggested snake_case key. Per-endpoint validation rules are documented in the reference.

Quickstart: the applicant name fields and what replaced first_name / last_name / legal_name

Example response

{
  "error": {
    "type": "https://docs.checktiv.com/api/errors/validation_error",
    "code": "validation_error",
    "message": "Invalid request body",
    "request_id": "req_01HEXAMPLE0000000000000000",
    "doc_url": "https://docs.checktiv.com/api/errors/validation_error",
    "details": {
      "issues": [
        {
          "code": "unrecognized_keys",
          "path": [],
          "keys": [
            "familyName"
          ],
          "message": "Unknown field \"familyName\". Did you mean \"family_name\"?"
        }
      ]
    }
  }
}