Skip to main content

Idempotency

Retry safely without creating duplicates. Every POST endpoint accepts an optional Idempotency-Key header. If you send the same key twice within 24 hours, AutoRev returns the original response without re-executing the operation.

When to use it​

  • Placing an outbound call (POST /api/v1/receptionists/:id/calls). A retry would otherwise dial twice.
  • Sending SMS (POST /api/v1/receptionists/:id/sms). A retry would otherwise text twice.
  • Provisioning a receptionist (POST /api/v1/receptionists). A retry would consume a plan slot.
  • Any POST from a background job that might retry on timeout.

How it works​

  1. Generate a unique string. UUIDv4 is recommended; max 255 characters, ASCII only.
  2. Send it in the Idempotency-Key header alongside your request.
  3. On the first call, AutoRev executes normally and caches the response body and status under the key.
  4. On any retry within 24 hours using the same key, AutoRev returns the cached response with an Idempotency-Replayed: true header.
  5. After 24 hours the key expires and can be reused.
curl -X POST https://app.autorev.ai/api/v1/receptionists/RECEPTIONIST_ID/calls \
  -H "Authorization: Bearer ar_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ "to": "+12125551234", "purpose": "appointment_reminder" }'

# First call: 202 Accepted, dials the number.
# Retry with same key: 202 Accepted + "Idempotency-Replayed: true" header.
#   No second dial. No duplicate charge.

Namespacing​

Idempotency keys are namespaced per tenant. Two API keys in the same account share the idempotency namespace, so a retry from either key hits the same cache. The same key string in two different tenants will not collide.

Caveats​

  • Only 2xx responses are cached. A 4xx or 5xx does not lock in the idempotency key, so you can fix the payload and retry with the same key. Failed network requests that never reached AutoRev are also safe to retry with the same key.
  • The request body is not validated against the cached entry. If you reuse a key with a different body, you still get the original response, not an error.
  • Max key length: 255 characters. Stick to ASCII.