Error codes

invalid_idempotency_key

HTTP status: 400
Retry: No
Execution: Nothing was done
Admin needed: No

Invalid Idempotency-Key. The Idempotency-Key header was present but empty, too long, or contained spaces or non-ASCII characters.

What it means

The API returns HTTP 400 with error.code set to invalid_idempotency_key. The default message is: "The Idempotency-Key header must be 1 to 255 printable ASCII characters with no spaces."

Common causes

A key longer than 255 characters.
A key containing spaces, tabs or non-ASCII characters.

How to identify it

Check the response status (400) and error.code (invalid_idempotency_key). 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 UUID v4 or another URL-safe token of at most 255 characters.

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

Send a valid key. Nothing was done.

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": "invalid_idempotency_key",
    "message": "The Idempotency-Key header must be 1 to 255 printable ASCII characters with no spaces.",
    "details": {},
    "request_id": "req_oow7drypdti4zyumdehx6iuz",
    "retry": "no",
    "doc_url": "https://docs.relationsai.com/errors/invalid_idempotency_key"
  }
}

Incorrect and corrected request

Incorrect: The key contains spaces.

Text
POST /v1/calls
Authorization: Bearer rai_test_YOUR_TEST_KEY
Content-Type: application/json
Idempotency-Key: call Asha retry 1

{
  "agent_id": "agent_4Nf8Gt2Hx6Jq9Lm3Pv7Rs1",
  "to": "+12025550100"
}

Corrected: A UUID v4: printable ASCII, no spaces, at most 255 characters.

Text
POST /v1/calls
Authorization: Bearer rai_test_YOUR_TEST_KEY
Content-Type: application/json
Idempotency-Key: 6f1d2c84-5b7e-4a3f-9c2d-8e1b0a7f4d63

{
  "agent_id": "agent_4Nf8Gt2Hx6Jq9Lm3Pv7Rs1",
  "to": "+12025550100"
}

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.

invalid_cursor invalid_json