Copy page

Error codes

idempotency_key_reused

Idempotency-Key reused. Within 24 hours an Idempotency-Key identifies one request: same method, path and body. Sending the key with a different body or to a different operation is refused so a retry can never silently do something else.

What it means

The API returns HTTP 409 with error.code set to idempotency_key_reused. The default message is: "This Idempotency-Key was already used with a different request."

Common causes

• The same key was used for two different operations.
• The body changed between retries.

How to identify it

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

• Use a new key for a new operation. For a retry, send exactly the original request.

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

Generate a new key for the new request. The original request with this key is unaffected.

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": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request.",
    "details": {},
    "request_id": "req_ot57su2lklzm53wt35jhp5o2",
    "retry": "no",
    "doc_url": "https://docs.relationsai.com/errors/idempotency_key_reused"
  }
}

Operations that can return this error

• POST /calls: Place a call
• POST /campaigns: Create a campaign
• POST /campaigns/{campaign_id}/recipients: Add recipients
• POST /campaigns/{campaign_id}/start: Start a campaign
• POST /campaigns/{campaign_id}/pause: Pause a campaign
• POST /campaigns/{campaign_id}/resume: Resume a campaign
• POST /campaigns/{campaign_id}/stop: Stop a campaign
• POST /contacts: Create a contact
• POST /contacts/upsert: Create or update a contact by phone number
• DELETE /contacts/{contact_id}: Delete a contact
• POST /dnc-entries: Add a number to the do-not-call list
• DELETE /dnc-entries/{dnc_entry_id}: Remove a number from the do-not-call list
• POST /webhook-endpoints: Create a webhook endpoint
• DELETE /webhook-endpoints/{webhook_endpoint_id}: Delete a webhook endpoint
• POST /webhook-endpoints/{webhook_endpoint_id}/rotate-secret: Rotate a webhook signing secret
• POST /webhook-endpoints/{webhook_endpoint_id}/test: Send a test event
• POST /webhook-deliveries/{webhook_delivery_id}/retry: Retry a delivery

See all codes in the error-code reference.