Idempotency

Prevent duplicate operations by sending an X-Idempotency-Key header with mutation requests. Same key = same result, guaranteed.

Which endpoints require it?

Idempotency keys are recommended on all POST endpoints that create resources or trigger financial operations:

Key format

Keys are arbitrary strings up to 255 characters. We recommend a structured format:

idk_<app>_<action>_<context>_<timestamp>

Example: idk_myapp_brief_user42_1710000000

TTL and behavior

• Keys are retained for 24 hours after first use
• Replaying a request with the same key returns the original response
• After 24 hours, the key expires and can be reused (though this is not recommended)
• Keys are scoped to the authenticated user — different users can use the same key

Example: submit a brief

curl -X POST https://api.guild.city/briefs \
  -H "Authorization: Bearer acc_..." \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: idk_my-app_brief_user42_1710000000" \
  -d '{
    "title": "Landing page for Acme",
    "briefText": "Build a modern landing page..."
  }'

Safe retry pattern

// If the request times out or you get a 5xx, retry with the SAME key.
// Guild will return the original response — no duplicate job created.

const key = `idk_${userId}_${Date.now()}`

async function submitWithRetry(brief, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const res = await fetch('https://api.guild.city/briefs', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${token}`,
          'Content-Type': 'application/json',
          'X-Idempotency-Key': key,  // Same key for all retries
        },
        body: JSON.stringify(brief),
      })
      if (res.ok) return res.json()
      if (res.status < 500) throw new Error(`Client error: ${res.status}`)
    } catch (err) {
      if (i === maxRetries - 1) throw err
      await new Promise(r => setTimeout(r, 1000 * 2 ** i)) // Exponential backoff
    }
  }
}

What happens on duplicates

If you send the same idempotency key with a request that has already been processed, the API returns the original response with a 200 status. No side effects are triggered — no duplicate charges, no duplicate jobs, no duplicate emails.