Error codes

invalid_phone_number

HTTP status: 400
Retry: No
Execution: Nothing was done
Admin needed: No

Invalid phone number. Phone numbers must be E.164 strings: a +, the country code and the subscriber number, digits only, at most 15 digits (for example +919000000001).

What it means

The API returns HTTP 400 with error.code set to invalid_phone_number. The default message is: "The phone number is not a valid E.164 number."

Common causes

A local format such as 09000000001 or (202) 555-0100.
Spaces, dashes or letters in the number.
A number too short or too long for E.164.

How to identify it

Check the response status (400) and error.code (invalid_phone_number). 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

Normalize numbers to E.164 before sending them.

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": "invalid_phone_number",
    "message": "The phone number is not a valid E.164 number.",
    "details": {
      "field": "to"
    },
    "request_id": "req_m3wrr5j6pwetgyu2pu4iwkmm",
    "retry": "no",
    "doc_url": "https://docs.relationsai.com/errors/invalid_phone_number"
  }
}

Incorrect and corrected request

Incorrect: A local format with a leading zero and no country code.

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

{
  "agent_id": "agent_4Nf8Gt2Hx6Jq9Lm3Pv7Rs1",
  "to": "09000000001"
}

Corrected: The same number in E.164: +, the country code, then the subscriber number.

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

{
  "agent_id": "agent_4Nf8Gt2Hx6Jq9Lm3Pv7Rs1",
  "to": "+919000000001"
}

Operations that can return this error

POST /calls: Place a call
POST /contacts: Create a contact
POST /contacts/upsert: Create or update a contact by phone number
PATCH /contacts/{contact_id}: Update a contact
POST /dnc-entries: Add a number to the do-not-call list
GET /dnc-entries: List or look up do-not-call entries
GET /contacts: List contacts
GET /calls: List calls

See all codes in the error-code reference.

invalid_json validation_error