# validation_error

- HTTP status: 400
- Retry: No
- Execution: not started
- Admin needed: no

**Validation failed.** The request was well formed JSON but one or more fields, query parameters or headers broke the documented rules. `details.errors` lists every problem found, not just the first.

## What it means

The API returns HTTP 400 with `error.code` set to `validation_error`. The default message is: "One or more fields are invalid."

## Common causes

- A required field is missing.
- A field has the wrong type, is too long, or is outside its allowed values.
- A field that the operation does not accept was sent (request bodies are strict).
- An unknown query parameter or an invalid `limit`.

## How to identify it

Check the response status (`400`) and `error.code` (`validation_error`). Branch on `error.code`, not on the message text: messages can be reworded, codes do not change within v1. Log `error.request_id` (also sent as the `X-Request-Id` header) so support can find the request.

## How to fix it

- Read `details.errors[].field` and `details.errors[].issue`, correct each field and resend.

## Retry guidance

Sending the request unchanged fails the same way. Fix the cause first (see How to fix it), then send it again.

## Did anything happen?

This request was refused before any call was placed and before anything was charged.

## Idempotency

Nothing was done. Fix the request and send it again; if you sent an Idempotency-Key you may reuse it, because a refused request is not stored.

## Who can fix it

The developer who sends the request can fix it; no administrator action is normally needed.

## When to contact support

If the error persists after the steps above, contact [support@relationsai.com](mailto:support@relationsai.com). See [Support](/resources/support) for what to include (the `request_id`, the time in UTC, the operation, and whether you used a test or live key) and what never to send (API keys, Authorization headers, webhook signing secrets, recording links, transcripts or customer data).

## Example error response

```json
{
  "error": {
    "code": "validation_error",
    "message": "One or more fields are invalid.",
    "details": {
      "errors": [
        {
          "field": "agent_id",
          "issue": "required",
          "message": "agent_id is required."
        }
      ]
    },
    "request_id": "req_os35ljoytapm22npytlktnvc",
    "retry": "no",
    "doc_url": "https://docs.relationsai.com/errors/validation_error"
  }
}
```

## Incorrect and corrected request

Incorrect: `priority` is not a field of the request; request bodies are strict, so the whole request is refused.

```http
POST /v1/calls
Authorization: Bearer rai_test_YOUR_TEST_KEY
Content-Type: application/json

{
  "agent_id": "agent_4Nf8Gt2Hx6Jq9Lm3Pv7Rs1",
  "to": "+12025550100",
  "priority": "high"
}
```

Corrected: Only documented fields. Values your agent needs go in `variables`, your own references in `metadata`.

```http
POST /v1/calls
Authorization: Bearer rai_test_YOUR_TEST_KEY
Content-Type: application/json

{
  "agent_id": "agent_4Nf8Gt2Hx6Jq9Lm3Pv7Rs1",
  "to": "+12025550100"
}
```

See all codes in the [error-code reference](/fundamentals/error-codes).