Copy page

Error codes

precondition_required

If-Match required. Campaigns and contacts are updated with optimistic concurrency. Send the ETag from your latest read in If-Match, so an update never overwrites a change you have not seen. If-Match: * matches any current version: the update is applied without the concurrency check (use it only when overwriting whatever is there is what you want).

What it means

The API returns HTTP 428 with error.code set to precondition_required. The default message is: "This update needs an If-Match header with the ETag of the version you read."

Common causes

• The If-Match header was not sent.

How to identify it

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

How to fix it

• Retrieve the resource, copy its ETag response header into If-Match, and resend.

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

PATCH does not use an Idempotency-Key.

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": "precondition_required",
    "message": "This update needs an If-Match header with the ETag of the version you read.",
    "details": {},
    "request_id": "req_eesgkbbtxvpr6b6cu4zcwb7o",
    "retry": "no",
    "doc_url": "https://docs.relationsai.com/errors/precondition_required"
  }
}

Incorrect and corrected request

Incorrect: A PATCH without If-Match.

Text
PATCH /v1/campaigns/cmp_3Uat7Kq2Lm9Px4Rv8Ny5Bc
Authorization: Bearer rai_test_YOUR_TEST_KEY
Content-Type: application/json

{
  "name": "October renewals"
}

Corrected: The ETag from the latest GET of the campaign, sent as If-Match.

Text
PATCH /v1/campaigns/cmp_3Uat7Kq2Lm9Px4Rv8Ny5Bc
Authorization: Bearer rai_test_YOUR_TEST_KEY
Content-Type: application/json
If-Match: "c3f1a9e2b7d4"

{
  "name": "October renewals"
}

Operations that can return this error

• PATCH /campaigns/{campaign_id}: Update a campaign
• PATCH /contacts/{contact_id}: Update a contact

See all codes in the error-code reference.