Copy page

Error codes

recipient_contacts_not_found

Contacts not found. Recipients are contacts. Every id in contact_ids must be a contact in this workspace and mode. Nothing was added.

What it means

The API returns HTTP 422 with error.code set to recipient_contacts_not_found. The default message is: "Some contact ids do not name contacts in this workspace."

Common causes

• A typo in a contact id.
• A contact from the other mode (test vs live).
• A deleted contact.

How to identify it

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

• Create the contacts first (POST /v1/contacts/upsert), then add their ids.

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

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": "recipient_contacts_not_found",
    "message": "Some contact ids do not name contacts in this workspace.",
    "details": {
      "contact_ids": [
        "ct_9Zx4Vb7Nm2Qw5Er8Ty1Ui3"
      ]
    },
    "request_id": "req_o2wrow7w2xqufsvsn4ksojj3",
    "retry": "no",
    "doc_url": "https://docs.relationsai.com/errors/recipient_contacts_not_found"
  }
}

Incorrect and corrected request

Incorrect: The id names no contact in this workspace and mode (for example a live contact with a test key).

Text
POST /v1/campaigns/cmp_2Kd7Fg4Hj9Lz3Xc8Vb5Nm1/recipients

{
  "contact_ids": [
    "ct_9Zx4Vb7Nm2Qw5Er8Ty1Ui3"
  ]
}

Corrected: Create (or find) the contact in the same mode first, then add the id it returns.

Text
POST /v1/contacts/upsert

{
  "phone_number": "+12025550102"
}

Operations that can return this error

• POST /campaigns: Create a campaign
• POST /campaigns/{campaign_id}/recipients: Add recipients

See all codes in the error-code reference.