Idempotency

All POST, PATCH, and DELETE requests accept an Idempotency-Key header. Retry with the same key and Deck returns the original response instead of performing the operation again. GET requests are naturally idempotent and do not require a key.

How it works

Include an Idempotency-Key header on any POST, PATCH, or DELETE request.

curl -X POST https://api.deck.co/v2/agents \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ "name": "Hotel Reservations" }'

When Deck receives a request with an idempotency key and the request succeeds, it caches the response and associates it with that key. Only successful responses are cached. If the original request returned an error, retrying with the same key will execute the request again. Keys are scoped to your organization, so different organizations can use the same key independently. If the same key is sent again:

Same parameters: Deck returns the cached response. The operation is not repeated.
Different parameters: Deck returns a 409 Conflict with an idempotency_error to prevent accidental misuse.
After 24 hours: the key expires and can be reused.

When to use them

Use idempotency keys on any create operation where a duplicate would cause problems:

Operation	Why
Storing a credential	Prevents duplicate credentials for the same user
Running a task	Prevents the same task from executing twice
Creating agents, sources, tasks	Prevents duplicate resources
Creating event destinations	Prevents duplicate webhook subscriptions
Updating or deleting resources	Guarantees the operation happens exactly once

You don’t need idempotency keys for GET requests. Reads are naturally idempotent.

Key format

Keys can be any string up to 256 characters. Keys longer than 256 characters are rejected with a 400 error.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Common patterns:

Pattern	Example	When to use
Business logic key	`user_456_run_task_789`	When the operation maps to a domain action
Request identifier	`req_20260218_abc123`	When you track requests in your system
UUID	`550e8400-e29b-41d4-a716-446655440000`	When you need a guaranteed-unique random key

Generating keys

const { randomUUID } = require('crypto')
const idempotencyKey = randomUUID()

const idempotencyKey = `user_${userId}_run_${taskId}`

import uuid
idempotency_key = str(uuid.uuid4())

idempotency_key = f"user_{user_id}_run_{task_id}"

Retry pattern

A typical retry flow with idempotency:

async function createAgent(name, retries = 3) {
  const idempotencyKey = `create_agent_${name}`

  for (let attempt = 1; attempt <= retries; attempt++) {
    try {
      const res = await fetch('https://api.deck.co/v2/agents', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.DECK_API_KEY}`,
          'Content-Type': 'application/json',
          'Idempotency-Key': idempotencyKey,
        },
        body: JSON.stringify({ name }),
      })

      return await res.json()
    } catch (err) {
      if (attempt === retries) throw err
      await new Promise(r => setTimeout(r, 1000 * attempt))
    }
  }
}

The key stays the same across retries. If the first request succeeded but the response was lost, the second request returns the cached result. If the first request failed or never reached the server, the second one executes normally since only successful responses are cached.

Error handling

Key reuse with different parameters returns HTTP 409:

{
  "errors": [
    {
      "type": "idempotency",
      "code": "idempotency_error",
      "message": "Idempotency key has already been used with different parameters."
    }
  ],
  "request_id": "req_a1b2c3d4..."
}

If you see this error, use a new key for the new request. Key exceeds 256 characters returns HTTP 400:

{
  "errors": [
    {
      "type": "idempotency",
      "code": "idempotency_key_error",
      "message": "Idempotency key must be at most 256 characters"
    }
  ],
  "request_id": "req_a1b2c3d4..."
}

Get Started

Guides

Development

Platform

Integrations

Migration Guides

How it works

When to use them

Key format

Generating keys

Retry pattern

Error handling

​How it works

​When to use them

​Key format

​Generating keys

​Retry pattern

​Error handling

How it works

When to use them

Key format

Generating keys

Retry pattern

Error handling