API errors

Validation failed

One or more fields in the request failed validation. The errors array lists each field and what is wrong with it.

400application/problem+json

What it means

The request reached the API and parsed correctly, but one or more values in it are not valid. Unlike the other error types, this problem document uses the ValidationError shape: alongside the standard RFC 9457 fields it carries an errors array with one entry per failing field.

Each entry names the offending property in field and explains the rule it broke in detail.

400 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/validation-failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "Request contains invalid fields",
  "errors": [
    {
      "field": "planReference",
      "detail": "Must be a valid 14-character plan reference"
    }
  ]
}

How to handle it

Read errors[] rather than the top-level detail. The top-level detail is a generic summary; the per-field entries are the actionable part.
Fix the named fields and resend. The same request will fail the same way until it changes, so do not retry automatically.
Log or surface each entry's field and detail as they are. They are written to be shown to a developer.
If a value looks right to you, check its format on the endpoint's reference page. A plan reference, for example, must be exactly 14 characters.

Errors reference

What it means

How to handle it

Related