Idempotência e erros

A API pública foi projetada para que integrações possam repetir requisições com segurança sem criar envelopes, participantes ou operações duplicadas.

`Idempotency-Key`

Todas as requisições POST em /v4/api/* exigem o header Idempotency-Key.

A chave deve:

ter entre 8 e 255 caracteres;

usar somente caracteres ASCII imprimíveis;

identificar uma única intenção de negócio;

ser reutilizada somente com o mesmo método, rota e corpo.

Uma boa chave combina o identificador estável do seu sistema com a operação, sem incluir dados pessoais. Exemplo: erp-184-criar-envelope.

O que acontece em cada cenário

Situação	Resposta	O que fazer
Primeira requisição válida	A operação é executada e a resposta bem-sucedida é guardada por 24 horas	Armazene a chave junto ao identificador da operação no seu sistema
Mesma chave e mesmo conteúdo	A resposta original é devolvida com `Idempotency-Replayed: true`	Trate como sucesso; não crie outra operação
Mesma chave ainda em processamento	`409 IDEMPOTENCY_KEY_IN_USE`	Aguarde e repita com a mesma chave
Mesma chave com conteúdo diferente	`422 IDEMPOTENCY_KEY_REUSE`	Corrija a integração; use uma nova chave apenas para uma nova intenção
Serviço de idempotência indisponível	`503 IDEMPOTENCY_UNAVAILABLE`	Não troque a chave; aplique retry com backoff
A primeira tentativa falha	A reserva é liberada	Corrija a causa e repita com a mesma chave
Repetir `POST /v4/api/webhooks/` já concluído	`409 IDEMPOTENCY_SECRET_NOT_REPLAYABLE` com o id do endpoint (o segredo de assinatura nunca é guardado para replay)	Não crie outro endpoint; gire o segredo em `POST /v4/api/webhooks/{webhookId}/secret/rotate`

Somente respostas bem-sucedidas são armazenadas para replay. Nunca gere uma chave nova apenas porque ocorreu timeout: a primeira requisição pode ter sido concluída.

Exemplo

Formato de erro

A resposta de erro usa o objeto error. O campo code deve orientar a lógica da integração; message serve para diagnóstico humano.

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Envelope not found"
  }
}

Erros de validação podem trazer uma lista de campos inválidos. Não dependa do texto exato da mensagem para tomar decisões automáticas.

Códigos HTTP mais comuns

HTTP	Significado	Ação recomendada
`400`	Corpo, parâmetro ou header inválido	Corrija a requisição; não repita sem alteração
`401`	Chave ausente, inválida ou revogada	Confira o header `Authorization` e a credencial
`403`	A conta ou a credencial não pode executar a ação	Confira permissões, plano e vínculo do recurso com a conta
`404`	Recurso não encontrado ou não visível para a conta	Confira o ID e evite revelar existência de recursos de outra conta
`409`	Operação concorrente ou estado incompatível	Leia o código do erro; aguarde antes de repetir quando aplicável
`422`	Semântica inválida, incluindo reutilização incorreta da chave	Corrija os dados ou a chave conforme o código
`429`	Limite de requisições excedido	Respeite `Retry-After` e aplique backoff com jitter
`503`	Proteção crítica temporariamente indisponível	Repita de forma segura com a mesma `Idempotency-Key`

Política de retry

Repita automaticamente apenas falhas transitórias: 429, 502, 503, 504 e erros de rede.

Use backoff exponencial com jitter.

Respeite o header Retry-After quando presente.

Mantenha a mesma Idempotency-Key em todas as tentativas da mesma operação.

Não repita automaticamente 400, 401, 403, 404 ou 422 sem corrigir a causa.

Suporte

Ao abrir um chamado, informe o horário com fuso, método, rota, status HTTP, error.code e o identificador do recurso. Nunca envie a API Key completa.

Idempotency-Key#

O que acontece em cada cenário#

Exemplo#

Formato de erro#

Códigos HTTP mais comuns#

Política de retry#