Copy page

Error codes

phone_number_not_usable

Phone number cannot be used for this call. The phone_number_id names a number in your workspace, but it cannot be used as the caller number for this agent: it does not support outbound calls, or it is not connected for calling.

What it means

The API returns HTTP 422 with error.code set to phone_number_not_usable. The default message is: "This phone number cannot place outbound calls for this agent."

Common causes

• The number is inbound only.
• The number is not connected for calling yet.

How to identify it

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

• Pick a number whose capabilities.outbound is true, or omit phone_number_id to use the agent's outbound number.

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 and the refusal is not stored under the Idempotency-Key. Fix the cause, then send the same request (with the same key if you sent one).

Who can fix it

A workspace administrator usually has to act, in the RelationsAI console.

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": "phone_number_not_usable",
    "message": "This phone number cannot place outbound calls for this agent.",
    "details": {
      "phone_number_id": "pn_5Lq8Xc2Rk9TzW3mBv7Np4d"
    },
    "request_id": "req_sg7b4vcijdoiigjq5ao6xjs4",
    "retry": "no",
    "doc_url": "https://docs.relationsai.com/errors/phone_number_not_usable"
  }
}

Incorrect and corrected request

Incorrect: The pinned number is inbound only (capabilities.outbound is false).

Text
POST /v1/calls

{
  "agent_id": "agent_3hT9kQ2mVx7RbN4pLc8Wz1",
  "to": "+919000000001",
  "phone_number_id": "pn_7Qw2Er4Ty6Ui8Op1As3Df5"
}

Corrected: Pins a number whose capabilities.outbound is true and that lists the agent in outbound_agent_ids (or omits phone_number_id).

Text
POST /v1/calls

{
  "agent_id": "agent_3hT9kQ2mVx7RbN4pLc8Wz1",
  "to": "+919000000001",
  "phone_number_id": "pn_5Lq8Xc2Rk9TzW3mBv7Np4d"
}

Operations that can return this error

• POST /calls: Place a call

See all codes in the error-code reference.