Idempotência

Para que serve

Se uma requisição POST falha por rede ou tempo esgotado, você não sabe se ela foi executada, e enviar de novo pode criar um segundo ticket. O cabeçalho Idempotency-Key resolve isso: repetir a mesma requisição com a mesma chave devolve a resposta da primeira, sem executar de novo.

Como usar

O cabeçalho é aceito em todo POST e é opcional: sem ele, a requisição é executada normalmente. Nos outros métodos ele é ignorado.
O valor tem de 1 a 255 caracteres ASCII visíveis. Use um UUID v4.
A janela é de 24 horas: nesse período, a mesma chave devolve a resposta original, com o cabeçalho Idempotent-Replayed: true. O corpo é o da primeira resposta, inclusive o requestId e o idioma dela; o cabeçalho X-Request-Id é o da requisição nova.
A chave vale por chave de API: a mesma chave enviada por outra chave de API é outra operação.
Respostas 401, 403, 404, 405, 429 e 5xx não ficam guardadas; você pode repetir depois de corrigir a causa. As respostas 4xx restantes (como 400 e 422) ficam guardadas e se repetem por 24 horas: depois de corrigir um corpo recusado com 422, use uma chave nova, porque a mesma chave com o corpo corrigido devolve idempotency_key_reused.
No envio de anexo (multipart/form-data), o conteúdo do arquivo não entra na comparação: repetir a mesma chave com outro arquivo devolve a resposta original. Use uma chave nova para cada arquivo novo.

curl -X POST "https://public-api.mspdesk.com.br/v1/tickets" \
  -H "Authorization: Bearer $MSPDESK_API_KEY" \
  -H "Idempotency-Key: 3f6c1c52-8f0e-4a55-9b1d-2a7e9c0b7d11" \
  -H "Content-Type: application/json" \
  --data @ticket.json

Gere a chave por operação, não por tentativa

Crie a chave uma vez para cada operação de negócio (por exemplo, ao registrar “abrir ticket do alerta 123” na sua fila) e reutilize-a em todas as tentativas. Uma chave nova a cada tentativa anula a proteção. Repetir uma requisição com a chave também consome o limite de uso; veja Limites de uso.

Erros

Chave reutilizada com outro corpo. A mesma chave com método, rota, parâmetros ou corpo diferentes é recusada. Use uma chave nova para uma operação nova.

{
  "code": "idempotency_key_reused",
  "detail": "A chave de idempotência foi usada com um corpo de requisição diferente.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 422,
  "title": "Chave de idempotência reutilizada",
  "type": "https://developers.mspdesk.com.br/erros/#idempotency_key_reused"
}

Requisição igual ainda em andamento. A primeira tentativa não terminou. Espere alguns segundos e repita com a mesma chave.

{
  "code": "idempotency_request_in_progress",
  "detail": "Uma requisição com a mesma chave de idempotência ainda está em execução.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 409,
  "title": "Requisição em andamento",
  "type": "https://developers.mspdesk.com.br/erros/#idempotency_request_in_progress"
}

Valor inválido. Vazio, com mais de 255 caracteres ou com caracteres fora do ASCII visível.

{
  "code": "invalid_idempotency_key",
  "detail": "O cabeçalho Idempotency-Key tem um formato inválido.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 400,
  "title": "Chave de idempotência inválida",
  "type": "https://developers.mspdesk.com.br/erros/#invalid_idempotency_key"
}

Serviço de idempotência indisponível. Quando o serviço que guarda as chaves está fora do ar, a resposta é 503. Nada foi executado: repita com a mesma chave depois de esperar.

{
  "code": "idempotency_unavailable",
  "detail": "Não foi possível garantir a idempotência da requisição neste momento. Tente novamente.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 503,
  "title": "Idempotência indisponível",
  "type": "https://developers.mspdesk.com.br/erros/#idempotency_unavailable"
}