> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# VALIDATION_ERROR

> The request body, query, or parameters failed schema validation, so the request was rejected with HTTP 422.

## What this error means

`VALIDATION_ERROR` is returned with HTTP status **422** when the request payload
fails schema validation: a required field is missing, a value has the wrong
type or an unknown enum member, or a cross-field rule is violated. The request
is not queued or partially processed; nothing is sent and no credits are
deducted.

Every response for this error carries this page's address in `meta.docs_url`:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Scheduled_at: must be a future timestamp",
    "status": 422,
    "details": {
      "issues": [
        { "field": "scheduled_at", "message": "must be a future timestamp" }
      ]
    }
  },
  "meta": {
    "request_id": "req_01J9ZKQ3V8",
    "docs_url": "https://docs.orbit.devotel.io/errors/VALIDATION_ERROR"
  }
}
```

## Cause

The `details.issues` array names each offending field and what went wrong;
schema-level rejections carry the same information in `details.validation`.
The most common causes are:

| Submitted value | Why it fails |
| - | - |
| `to_number` omitted entirely | A required field is missing from the body |
| `"limit": "ten"` | Wrong type: a number was expected |
| `"channel": "myspace"` | Unknown enum member: not a supported channel |
| Both `contact_id` and `identifier` set | A cross-field rule requires exactly one |
| `"scheduled_at"` in the past | The value is well-formed but not currently acceptable |

## How to fix it

1. **Read `details.issues`.** Each entry pairs a `field` path with a `message`;
   fix every listed field, not just the first, so the next attempt does not
   round-trip one issue at a time.
2. **Do not retry unchanged.** This is a deterministic rejection: the request
   will fail identically until the payload changes. Retrying without a fix
   only burns rate-limit budget.
3. **Validate early on your side.** Checking required fields, types, and enum
   values before sending catches most issues before they reach the API.
4. **Check the endpoint's reference page.** Field names, accepted formats, and
   cross-field rules are documented per endpoint in the API reference.

Once the payload is corrected, resend the request; earlier attempts changed
nothing server-side.

## Related

* [Error Code Reference](https://docs.orbit.devotel.io/reference/error-codes.md#from-a-code-to-a-runbook) —
  validation codes sit in the deterministic reject class: never retry until
  the payload changes.
* [Validation gates runbook](https://docs.orbit.devotel.io/troubleshooting/validation-gates.md) — decoding
  `details` and fixing the payload field by field.
* [Error Handling Examples](https://docs.orbit.devotel.io/guides/error-handling-examples.md) — response-envelope
  handling patterns in code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.