Repetição segura
Nas operações que aceitam Idempotency-Key, uma retentativa não repete o efeito; a resposta original nem sempre pode ser reproduzida.
Uma chamada pode estourar o tempo depois que o servidor já agiu: a ligação já foi discada, a execução já gastou tokens. Repetir às cegas faria o efeito — e a cobrança — duas vezes. Nas operações que aceitam Idempotency-Key, use a mesma chave para evitar repetir o efeito.
Idempotency-Key: b3f0c1e2-4a5b-4c6d-8e9f-0a1b2c3d4e5fComo usar
- Gere uma chave por intenção do usuário (um UUID serve), antes da primeira tentativa.
- Mande a mesma chave em todas as retentativas dessa intenção.
- Uma intenção nova ganha uma chave nova.
A chave vale por 24 horas e é separada por usuário.
Obrigatória ou opcional
Algumas operações que gastam dinheiro ou falam com terceiros — como executar um agente (POST /runs) ou abrir uma ligação — exigem a chave; sem ela a resposta é 400 IDEMPOTENCY_KEY_REQUIRED. Outras operações a aceitam como opcional, mas há POST que não declaram esse cabeçalho, como POST /sessions. Consulte os parâmetros de cada operação na referência antes de enviá-lo.
Respostas possíveis
| Situação | Resposta |
|---|---|
| Primeira vez | A operação roda normalmente. |
| Repetição de uma chamada concluída com resposta armazenada | A mesma resposta, com Idempotency-Replayed: true. Nada roda de novo. |
| A resposta não pode ser reproduzida (por exemplo, contém um segredo ou excede 1 MiB) | 409 IDEMPOTENCY_REPLAY_UNAVAILABLE. O efeito não se repete; consulte o recurso quando disponível. POST /me/token permite consultar GET /me/token, mas não recuperar o segredo da primeira resposta. |
| A primeira resposta foi um stream | O stream não é repetido; consulte o recurso indicado por Content-Location. |
| A primeira ainda está rodando | 409 IDEMPOTENCY_IN_PROGRESS com Retry-After: 1. Espere e repita. |
| Mesma chave com outra rota ou outro corpo | 422 IDEMPOTENCY_KEY_REUSED. É um erro do cliente: cada intenção tem sua chave. |
| A primeira foi abandonada no meio | 409 IDEMPOTENCY_IN_PROGRESS com details.reason = "abandoned". A API não reexecuta: consulte o recurso ou use uma chave nova. |