# validation-failed

# `validation-failed`

**HTTP 400.** The request reached the endpoint but one or more parameters did not match its schema.

Unlike the other problem types, this one carries an extra `errors` array naming each field that failed — permitted by [RFC 9457 §3.2](https://www.rfc-editor.org/rfc/rfc9457#section-3.2), which allows additional members on a problem document.

```json
{
  "type": "https://developers.supliful.com/errors/validation-failed",
  "title": "Request validation failed",
  "status": 400,
  "detail": "One or more request parameters are invalid.",
  "instance": "/v1/example",
  "errors": [
    { "path": "quantity", "message": "Expected number, received string" },
    { "path": "address.zip", "message": "Required" }
  ]
}
```

## Reading the `errors` array

Each entry has:

- **`path`** — the location of the offending value, dot-joined. Nested objects read as `address.zip`; array members include their index, as `lines.0.sku`.
- **`message`** — what was wrong with that specific value.

The array names **every** field that failed, not just the first, so a single round trip tells you everything you need to correct. There is no need to fix one field and resubmit to discover the next.

## How to fix it

Read the `path` values against the endpoint's schema in the [API Reference](/api), which is generated from the same definitions that perform this validation — so the reference and the validator cannot disagree.

The usual causes:

- A number sent as a string, typically from a template or a form encoding (`"3"` where `3` is expected).
- A missing required field, reported as `Required`.
- A timestamp not in ISO 8601 form.
- A field name that is close but not exact — casing and pluralisation are significant.

## Retry behaviour

Terminal. The same request will fail identically until the payload changes, so do not retry it unmodified. Log the `errors` array — it is the whole diagnosis, and it is not recoverable from the status code alone.