Copy page

Error codes

idempotency_outcome_unknown

Outcome of the earlier request unknown. The first request with this key was interrupted before its result was recorded. It may or may not have taken effect, so the API refuses to run it a second time under the same key. What is stored: the unfinished claim. For 24 hours from the first attempt, every request with this key answers this same error; after that the key is free again. A POST /v1/calls sent WITHOUT a key can also get this answer when the call may have started but could not be confirmed: nothing is stored then, and a retry places another call.

What it means

The API returns HTTP 409 with error.code set to idempotency_outcome_unknown. The default message is: "An earlier request with this Idempotency-Key did not finish, and its outcome is unknown."

Common causes

• The earlier request was interrupted by a server restart or a lost connection mid-operation.

How to identify it

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

• List or retrieve the resource (for a call, list calls filtered by to and created_after) to see whether the operation took effect.
• Only if it did not, send the operation again (with a NEW key if you use keys).

Retry guidance

Do not resend yet. First find out whether the operation took effect (see How to fix it), then act on what you find.

Did anything happen?

The work may have started before this error was returned. Do not assume nothing happened: read the resource (for a call, list calls filtered by to and created_after; for a campaign, retrieve it) before you send anything again. A charge may have been recorded for work that started; check the call or campaign before you act.

Idempotency

If you sent a key: keep the SAME key for any retry; for 24 hours from the first attempt it answers this same error, so it can never run the request twice. Never send the request with a new key (or without one) until you know it did not happen. If you sent no key, nothing protects a retry: it runs the request again. Either way, learn the outcome first: GET the resource, or list by to or your metadata; only if it did not happen, send it again.

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 state you read is still ambiguous after a few minutes, write to support@relationsai.com with the request_id. 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_outcome_unknown",
    "message": "An earlier request with this Idempotency-Key did not finish, and its outcome is unknown.",
    "details": {},
    "request_id": "req_ai4vrzgioj36wznhcobglbkh",
    "retry": "no",
    "doc_url": "https://docs.relationsai.com/errors/idempotency_outcome_unknown"
  }
}

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.