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-invalid on 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.