Skip to main content

Idempotency

Idempotency ensures that replaying a request multiple times has the same effect as sending it once. This is critical for network reliability.

Which Endpoints Require It​

The Idempotency-Key header is required on:

  • POST /agents — create a new agent
  • POST /calls — create a new call

All other endpoints (GET, DELETE, etc.) do not use idempotency keys.

The Header​

Pass a unique key for each logical operation:

curl -X POST https://api.dialogbrain.com/api/v1/agents \
  -H "X-API-Key: db_live_YOUR_KEY" \
  -H "Idempotency-Key: my-agent-creation-12345" \
  -H "Content-Type: application/json" \
  -d '{"name": "Booking assistant", "prompt_text": "You confirm bookings."}'

Missing Key → 400 Bad Request​

If you forget the header:

{
  "detail": "Idempotency-Key header is required"
}

Status: 400 Bad Request

Behavior During Retry​

Same Key + Same Body → Original Response​

If you send the same request twice:

# First request
curl -X POST https://api.dialogbrain.com/api/v1/agents \
  -H "X-API-Key: db_live_YOUR_KEY" \
  -H "Idempotency-Key: create-agent-1" \
  -d '{"name": "Booking assistant", "prompt_text": "You confirm bookings."}'

# Response (201 Created):
# {"id": 42, "name": "Booking assistant", ...}

# Second request with same key and body
curl -X POST https://api.dialogbrain.com/api/v1/agents \
  -H "X-API-Key: db_live_YOUR_KEY" \
  -H "Idempotency-Key: create-agent-1" \
  -d '{"name": "Booking assistant", "prompt_text": "You confirm bookings."}'

# Response (201 Created, same agent):
# {"id": 42, "name": "Booking assistant", ...}

The second request returns the same agent without creating a duplicate.

Same Key + Different Body → 409 Conflict​

If you retry with the same key but different request body:

curl -X POST https://api.dialogbrain.com/api/v1/agents \
  -H "X-API-Key: db_live_YOUR_KEY" \
  -H "Idempotency-Key: create-agent-1" \
  -d '{"name": "Different name", "prompt_text": "Something else."}'

# Response (409 Conflict):
{
  "detail": "Idempotency key already used with a different request body"
}

This prevents accidental misuse of the key.

Same Key In-Flight → 409 Conflict with Retry-After​

If a request with the same key is currently in progress:

{
  "detail": "Request with this idempotency key is already in progress"
}

Status: 409 Conflict
Header: Retry-After: 2 (wait at least 2 seconds before retrying)

Key Expiration​

Idempotency keys are valid for 24 hours from the time of the first request. After 24 hours, the key is discarded and can be reused for a new operation.

Example: if you create an agent with key create-agent-1 on Monday, you can safely reuse create-agent-1 on Tuesday to create a different agent.

Using the Python SDK​

The SDK automatically generates and manages idempotency keys. Pass idempotency_key= to explicitly set one:

from dialogbrain import DialogBrainClient

async with DialogBrainClient(api_key="db_live_YOUR_KEY") as client:
    # SDK auto-generates a UUID for idempotency
    agent = await client.agents.create(
        name="Booking assistant",
        prompt_text="You confirm bookings."
    )
    
    # Or provide your own key
    agent = await client.agents.create(
        name="Booking assistant",
        prompt_text="You confirm bookings.",
        idempotency_key="my-specific-key-123"
    )

The sync client works the same way:

from dialogbrain import SyncDialogBrainClient

with SyncDialogBrainClient(api_key="db_live_YOUR_KEY") as client:
    agent = client.agents.create(
        name="Booking assistant",
        prompt_text="You confirm bookings.",
        idempotency_key="my-specific-key-123"
    )

See also: Errors