Skip to main content

validation_error

The request body parsed cleanly, but at least one field failed validation. This is the most common error on the API, and the only one where details is always worth reading.

Status: 422

{
  "status": 422,
  "type": "validation_error",
  "message": "One or more fields are invalid",
  "request_id": "req_01J8K2P...",
  "doc_url": "https://docs.epostix.com/errors/validation_error",
  "details": [
    {"field": "from", "message": "property \"from\" is missing", "code": "required"},
    {"field": "subject", "message": "cannot be blank", "code": "invalid"}
  ]
}

Why you got this​

  • A required field is absent. code is required and field names it.
  • A field is the wrong type, such as a string where an array is expected.
  • A value is outside its allowed range: a subject over 255 characters, more than 50 tags, metadata over 10KB.
  • An enum field carries a value that is not in the enum.
  • A recipient address is not a valid mailbox.

How to fix it​

Read details rather than message. Each entry gives you the exact field path and a code you can branch on. required means the field is missing; invalid means it was present and unacceptable.

If details is empty, the whole body was rejected rather than a single field. That usually means a field is the wrong type at the top level.

Is it safe to retry​

No. The same request will fail the same way. Correct the field and send a new request.

Reusing the Idempotency-Key from a rejected request is safe, because a request that failed validation was never stored.