Copy page

Error codes

validation_error

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. See 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.

Text
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.

Text
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.