跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

Qoder Cloud Agents API 支持通过 幂等键（Idempotency Key） 确保写操作的安全重试。当网络不稳定或客户端超时时，使用幂等键可以避免重复创建资源或重复执行操作。

​
头部格式

支持两种等效的头部名称：
头部名称说明
Idempotency-Key标准格式
X-Idempotency-Key带 X- 前缀的兼容格式
两者功能完全相同，任选其一即可。 
# 方式一：标准格式
Idempotency-Key: unique-request-id-001

# 方式二：X- 前缀格式
X-Idempotency-Key: unique-request-id-001
推荐使用 UUID v4 作为幂等键值，确保全局唯一性。

​
适用范围

幂等键仅对 写操作 有效：
HTTP 方法支持幂等键说明
POST是创建资源
PUT是更新资源
DELETE是删除资源
GET否读操作天然幂等，无需此机制

​
使用示例

​
创建 Agent（带幂等键）

# 使用 UUID 作为幂等键
curl -X POST "https://openapi.qoder.sh/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "name": "my-agent",
    "model": "qoder-sonnet-latest"
  }'

​
使用脚本生成幂等键

# 自动生成 UUID 并发起请求
IDEMPOTENCY_KEY=$(uuidgen | tr '[:upper:]' '[:lower:]')

curl -X POST "https://openapi.qoder.sh/api/v1/cloud/sessions" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "agent_id": "agent_abc123"
  }'

echo "幂等键: $IDEMPOTENCY_KEY"

​
重复请求行为

​
相同幂等键 + 相同请求体

服务端直接返回首次请求的响应结果，不会重复执行操作： 
# 第一次请求 → 创建资源，返回 201
curl -X POST "https://openapi.qoder.sh/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-001" \
  -d '{"name": "test-agent", "model": "qoder-sonnet-latest"}'

# 第二次请求（相同 key + 相同 body）→ 直接返回首次结果
curl -X POST "https://openapi.qoder.sh/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-001" \
  -d '{"name": "test-agent", "model": "qoder-sonnet-latest"}'

​
相同幂等键 + 不同请求体

服务端返回 409 conflict_error，拒绝执行： 
{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "A request with this idempotency key has already been processed with different parameters."
  }
}
每个唯一的业务操作应使用独立的幂等键。不要为不同的请求复用同一个 key。

​
幂等键生命周期

特性说明
有效期幂等键在首次使用后保留 24 小时
过期后相同 key 将被视为新请求重新执行
作用域按 PAT（账户）隔离，不同账户的相同 key 互不影响

​
最佳实践

​
1. 何时使用幂等键

  • 创建关键资源（Agent、Session）时 强烈建议 使用
  • 网络不稳定环境下的所有写操作
  • 自动化脚本中的批量操作

​
2. Key 的生成策略

策略适用场景示例
UUID v4通用场景550e8400-e29b-41d4-a716-446655440000
业务 ID 组合业务去重create-agent-project42-env-prod
时间戳 + 随机数简单场景1717200000-abc123

​
3. 带重试的完整示例

#!/bin/bash
# 创建 Session，带幂等键和重试逻辑
IDEMPOTENCY_KEY=$(uuidgen | tr '[:upper:]' '[:lower:]')
MAX_RETRIES=3

for i in $(seq 1 $MAX_RETRIES); do
  response=$(curl -s -w "\n%{http_code}" \
    -X POST "https://openapi.qoder.sh/api/v1/cloud/sessions" \
    -H "Authorization: Bearer $QODER_PAT" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
    -d '{"agent_id": "agent_abc123"}')

  http_code=$(echo "$response" | tail -1)
  body=$(echo "$response" | sed '$d')

  # 成功或客户端错误（不需重试）
  if [ "$http_code" -lt 500 ] && [ "$http_code" != "429" ]; then
    echo "$body"
    break
  fi

  # 服务端错误，安全重试（幂等键确保不会重复创建）
  echo "第 $i 次请求失败 ($http_code)，重试中..."
  sleep $((i * 2))
done

​
不使用幂等键时的行为

  • 相同请求重复发送将 每次都执行，可能导致重复创建资源
  • 对于非关键操作或已在业务层做去重的场景，可以不使用幂等键
  • GET 请求无需幂等键，天然安全可重试