Validation errors
Map 422 field errors to accessible form messages without losing the user’s input.
The API returns 422 validation_failed when a form-configured required field is missing or a field is not allowed.
{
"success": false,
"error": {
"code": "validation_failed",
"message": "Check the submitted fields.",
"fields": {
"email": ["Invalid email address."]
}
},
"request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
}
Client handling
if (response.status === 422) {
const body = await response.json()
fieldErrors.value = body.error.fields ?? {}
summary.value = body.error.message
return
}
Guidelines:
- Keep the submitted values in the form.
- Show a summary with
role="alert". - Link each error to its input with
aria-describedby. - Set
aria-invalidon the field. - Move focus to the first invalid field or the error summary.
- Do not show raw API messages for non-field errors.
Reserved pseudo-fields
Some errors are reported against internal keys such as _payload, _fields or _idempotency_key. Map these to a general form message rather than a visible input.
When the form schema changes
Required fields and allowed field names are configured on the form in Postvia. The browser cannot infer them from the public API. Submit the fields the customer website actually uses and let the API enforce the configured rules.