validation_error (422)
validation_error
HTTP status: 422
Retryable: No. Retrying without changes will fail the same way.
The request body or query parameters were refused.
When it fires
A schema rejected an applicant or session resource request, or a list filter was refused. 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. Non-schema refusals also use this code: a tenant-scoped caller omitted session_id on GET /v1/webhook-events; a partition-scoped caller called GET /v1/wallet/transactions; an attested internal plane sent an Idempotency-Key; or an attested plane's body tenant_ref did not match its vouched partition. For a schema rejection, 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. On GET /v1/sessions, a status or outcome filter whose value is not in its list, or that was sent more than once, returns this code with param naming the filter and no details.issues; the message lists the values the filter accepts.
How to handle it
For a schema rejection, 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. For a refused list filter, send it once, with one of the values the message lists. For a non-schema refusal, read message and the optional param / details.reason. 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-dev.autohost-dev.uk/api/errors/validation_error",
"code": "validation_error",
"message": "Invalid request body",
"request_id": "req_01HEXAMPLE0000000000000000",
"doc_url": "https://docs-dev.autohost-dev.uk/api/errors/validation_error",
"details": {
"issues": [
{
"code": "unrecognized_keys",
"path": [],
"keys": [
"familyName"
],
"message": "Unknown field \"familyName\". Did you mean \"family_name\"?"
}
]
}
}
}