Copy page

Error codes

agent_not_ready

Agent not ready to call. The agent exists but cannot place calls yet. details.reasons lists every reason found, using the same codes as the agent readiness endpoint. Agents are created, configured, published and switched on in the console.

What it means

The API returns HTTP 422 with error.code set to agent_not_ready. The default message is: "This agent cannot place calls right now."

Common causes

• agent_paused: the agent is switched off in the console.
• agent_not_connected: the agent's setup is not finished (open it in the console and save it once).
• agent_not_published: the agent has never been published, or its live version is paused.
• no_outbound_number: no phone number in the workspace is assigned to this agent for outbound calls.

How to identify it

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

• Call GET /v1/agents/{agent_id}/readiness to see every reason.
• In the console, switch the agent on, publish it, and assign it an outbound phone 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 readiness reports agent_not_connected after saving the agent in the console, write to 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": "agent_not_ready",
    "message": "This agent cannot place calls right now.",
    "details": {
      "agent_id": "agent_3hT9kQ2mVx7RbN4pLc8Wz1",
      "reasons": [
        "agent_not_published"
      ]
    },
    "request_id": "req_dlph75zpjfcr7h3qgqtn6xo2",
    "retry": "no",
    "doc_url": "https://docs.relationsai.com/errors/agent_not_ready"
  }
}

Incorrect and corrected request

Incorrect: The agent is switched off (or unpublished) in the console.

Text
POST /v1/calls

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

Corrected: The same request, sent after the agent was switched on and published in the console (GET /v1/agents/{agent_id}/readiness reports ready: true). Nothing in the request itself changes.

Text
POST /v1/calls

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

Operations that can return this error

• POST /calls: Place a call
• POST /campaigns/{campaign_id}/start: Start a campaign
• POST /campaigns/{campaign_id}/resume: Resume a campaign

See all codes in the error-code reference.