Skip to main content
A rede pode cair depois que a API grava um recurso e antes que a resposta chegue ao seu sistema. Nesse caso, o seu sistema não sabe se a escrita aconteceu. Com o cabeçalho Idempotency-Key, o seu sistema repete a chamada, e a API grava o recurso uma vez só. O cabeçalho é opcional e vale para todo POST da API. Envie o cabeçalho em todo POST.

​
Como usar

  1. Crie um valor único para cada escrita. Um UUID serve.
  2. Guarde o valor junto da escrita no seu sistema.
  3. Envie o valor no cabeçalho Idempotency-Key da chamada POST.
  4. Se a resposta não chegar, repita a chamada com o mesmo valor e o mesmo conteúdo.

​
O que a API faz com o valor

A API compara cada chamada com a primeira chamada do mesmo valor. A comparação usa o método, o caminho, os parâmetros e o nome e o conteúdo de cada arquivo. A ordem dos campos no corpo não muda a comparação.

​
O que fazer com cada erro

​
As respostas que a API guarda

A API guarda a resposta de sucesso (2xx) e os erros 409 e 422 do recurso. A repetição devolve essa resposta como ela veio na primeira vez. Para corrigir uma chamada que recebeu 409 ou 422, use um valor novo. A API não guarda as outras respostas, como 400, 401, 402, 403, 404, 413, 429 e 5xx. Ela também não guarda os erros idempotency_key_in_use e idempotency_key_reused. A repetição de uma chamada sem resposta guardada roda de novo.

​
As regras

  • O valor tem de 1 a 255 caracteres. Um valor maior recebe 400 com o código invalid_parameter.
  • Cada chave de API tem os próprios valores. Duas chaves de API podem usar o mesmo valor sem conflito.
  • A repetição que recebe a resposta guardada não gasta uma escrita paga. Ela conta no limite de chamadas por minuto.
  • A API guarda a resposta por 24 horas. Depois desse prazo, a API pode apagar a resposta. A chamada com o mesmo valor roda então como nova.