Copy page

Error codes

consent_required

Consent required. The workspace's compliance settings require recorded consent before calling, and the destination matches a contact whose consent_granted is false. The rule applies only to numbers that match a contact: a number with no contact record is not checked for consent and is called (the do-not-call list, calling hours and the per-number daily limit still apply to it).

What it means

The API returns HTTP 422 with error.code set to consent_required. The default message is: "This contact has no recorded consent, and consent is required for calls in this workspace."

Common causes

• The contact has not given consent, or withdrew it. The call is refused for compliance.

How to identify it

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

What to do

• Do not retry: the same request is refused every time until consent is recorded.
• Record consent only when the person actually gave it: a workspace member who manages contacts sets it on the contact (PATCH /v1/contacts/{contact_id} with consent_granted: true using a key holding contacts:write, or the Contacts screen in the console). The change is recorded as a consent event.
• Whether consent is required at all is a compliance setting a workspace admin controls in the console.

Retry guidance

Do not resend the request, and do not change settings, to get around this refusal. A new request is appropriate only when the rule genuinely no longer applies: the person asked to be called or gave consent, or the permitted calling window has started.

Did anything happen?

This request was refused before any call was placed and before anything was charged.

Idempotency

No call was placed. If you sent an Idempotency-Key, the refusal is not stored under it. If the rule later stops applying (for example the person gives consent), place a new call (with a new key, if you use one).

Who can fix it

Nobody should change data to make this call go through. Remove a do-not-call entry or record consent only when the person asked you to, and keep a record of who asked and when; these changes are audited. See Consent and DNC.

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": "consent_required",
    "message": "This contact has no recorded consent, and consent is required for calls in this workspace.",
    "details": {},
    "request_id": "req_sydugolmpnl3rj7jfdqrc2nz",
    "retry": "no",
    "doc_url": "https://docs.relationsai.com/errors/consent_required"
  }
}

Operations that can return this error

• POST /calls: Place a call

See all codes in the error-code reference.