跳转到主要内容

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.

通过 Idempotency-Key 头确保写操作的安全重试，避免网络超时导致重复创建资源。

​
头部格式

在写操作（POST / PUT / DELETE）请求中添加 Idempotency-Key 头： 
Idempotency-Key: <UUID v4>
推荐使用 UUID v4 确保全局唯一。GET 请求天然幂等，无需此头。

​
重复请求行为

场景服务端响应
相同 key + 相同 body直接返回首次请求的响应（不重复执行）
相同 key + 不同 body409 conflict_error："Idempotency key reused with a different request body."
不带幂等键每次都执行，可能重复创建资源

​
生命周期

特性说明
有效期首次使用后保留 24 小时
过期后相同 key 被视为新请求
作用域按 PAT（账户）隔离

​
示例

# 带幂等键创建 Agent（超时可安全重试）
curl -X POST "https://api.qoder.com/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -d '{"name": "my-agent", "model": "ultimate"}'
创建关键资源（Agent、Session、Environment）时强烈建议使用幂等键。自动化脚本中的批量写操作也应每次生成独立 key。