Idempotency

The Bota API supports idempotency for safely retrying requests without performing the same operation twice. This is critical for operations that create resources or trigger processing jobs.

How It Works

Include an Idempotency-Key header with a unique value for each distinct operation:

curl -X POST https://api.bota.dev/v1/recordings \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: rec_create_user123_1704067200" \
  -H "Content-Type: application/json" \
  -d '{
    "end_user_id": "eu_abc123",
    "device_id": "dev_xyz789"
  }'

If you send the same request with the same idempotency key:

First request — Creates the resource and returns the response
Subsequent requests — Returns the cached response from the first request

Idempotency Key Requirements

Requirement	Details
Format	String, 1-255 characters
Characters	Alphanumeric, hyphens, underscores
Uniqueness	Must be unique per operation per project
TTL	Keys are stored for 24 hours

Recommended Key Patterns

# Pattern: {operation}_{entity}_{unique_id}_{timestamp}

rec_create_user123_1704067200
txn_start_rec456_1704067200
upload_complete_up789_1704067200

Using the same idempotency key for different request bodies will return an error. The key is tied to both the endpoint and the original request payload.

Supported Endpoints

Idempotency keys are supported on all POST endpoints that create resources or trigger jobs:

Endpoint	Use Case
`POST /end-users`	Creating end users
`POST /devices`	Registering devices
`POST /devices/:id/bind`	Binding devices to users
`POST /recordings`	Creating recordings
`POST /recordings/:id/upload-complete`	Completing uploads
`POST /transcriptions`	Starting transcription jobs
`POST /summaries`	Starting summarization jobs

Response Behavior

Successful Replay

When replaying a previously successful request:

{
  "id": "rec_abc123",
  "status": "created",
  "created_at": "2025-01-15T10:00:00Z"
}

The response includes the original resource, and no duplicate is created.

Error Replay

If the original request failed with a client error (4xx), the error is returned on replay. Server errors (5xx) are not cached — you can safely retry with the same key.

Key Conflict

If you reuse a key with a different request body:

{
  "error": {
    "code": "idempotency_key_conflict",
    "message": "Idempotency key was used with different request parameters",
    "param": "Idempotency-Key"
  }
}

Implementation Example

const crypto = require('crypto');

async function createRecordingIdempotent(endUserId, deviceId) {
  // Generate a unique key for this operation
  const idempotencyKey = `rec_create_${endUserId}_${Date.now()}`;

  const response = await fetch('https://api.bota.dev/v1/recordings', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.BOTA_API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,
    },
    body: JSON.stringify({
      end_user_id: endUserId,
      device_id: deviceId,
    }),
  });

  return response.json();
}

// Safe to retry on network errors
async function createRecordingWithRetry(endUserId, deviceId, maxRetries = 3) {
  const idempotencyKey = `rec_create_${endUserId}_${Date.now()}`;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch('https://api.bota.dev/v1/recordings', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.BOTA_API_KEY}`,
          'Content-Type': 'application/json',
          'Idempotency-Key': idempotencyKey,
        },
        body: JSON.stringify({
          end_user_id: endUserId,
          device_id: deviceId,
        }),
      });

      if (response.ok) {
        return response.json();
      }

      // Don't retry client errors
      if (response.status < 500) {
        throw new Error(`Client error: ${response.status}`);
      }
    } catch (error) {
      if (attempt === maxRetries) throw error;
      await new Promise(r => setTimeout(r, 1000 * attempt));
    }
  }
}

import os
import time
import requests

def create_recording_idempotent(end_user_id: str, device_id: str) -> dict:
    # Generate a unique key for this operation
    idempotency_key = f"rec_create_{end_user_id}_{int(time.time())}"

    response = requests.post(
        "https://api.bota.dev/v1/recordings",
        headers={
            "Authorization": f"Bearer {os.environ['BOTA_API_KEY']}",
            "Content-Type": "application/json",
            "Idempotency-Key": idempotency_key,
        },
        json={
            "end_user_id": end_user_id,
            "device_id": device_id,
        },
    )

    response.raise_for_status()
    return response.json()


def create_recording_with_retry(end_user_id: str, device_id: str, max_retries: int = 3) -> dict:
    idempotency_key = f"rec_create_{end_user_id}_{int(time.time())}"

    for attempt in range(1, max_retries + 1):
        try:
            response = requests.post(
                "https://api.bota.dev/v1/recordings",
                headers={
                    "Authorization": f"Bearer {os.environ['BOTA_API_KEY']}",
                    "Content-Type": "application/json",
                    "Idempotency-Key": idempotency_key,
                },
                json={
                    "end_user_id": end_user_id,
                    "device_id": device_id,
                },
            )

            if response.ok:
                return response.json()

            # Don't retry client errors
            if response.status_code < 500:
                response.raise_for_status()

        except requests.RequestException:
            if attempt == max_retries:
                raise
            time.sleep(attempt)

    raise Exception("Max retries exceeded")

Best Practices

Generate keys client-side

Always generate idempotency keys on the client before making the request. This ensures the same key is used across retries.

Include enough context

Include relevant identifiers in the key (user ID, timestamp) to make debugging easier and prevent accidental collisions.

Don't reuse keys across operations

Each distinct operation should have its own idempotency key. Reusing keys across different operations will cause conflicts.

Store keys for critical operations

For payment-like operations (e.g., triggering transcription jobs), store the idempotency key in your database so you can retry with the exact same key if needed.

​How It Works

​Idempotency Key Requirements

​Recommended Key Patterns

​Supported Endpoints

​Response Behavior

​Successful Replay

​Error Replay

​Key Conflict

​Implementation Example

​Best Practices

How It Works

Idempotency Key Requirements

Recommended Key Patterns

Supported Endpoints

Response Behavior

Successful Replay

Error Replay

Key Conflict

Implementation Example

Best Practices