Evite cobranças duplicadas e trate falhas sem perder o controle dos pedidos.
POST de cobranças aceita o cabeçalho opcional Idempotency-Key. Mesmo vendedor, mesma chave e mesmo conteúdo retornam a resposta já registrada; conteúdo diferente com a mesma chave gera 409 IDEMPOTENCY_MISMATCH.
Use de 16 a 128 caracteres: letras, números, hífen ou sublinhado. Gere uma chave estável por tentativa de compra e persista-a antes do envio. Após timeout, repita a mesma solicitação com a mesma chave e os mesmos campos. Não gere outra chave a cada repetição.
Não aplique esta garantia a saques, devoluções ou outros POSTs: o contrato atual não documenta idempotência nesses endpoints.
| HTTP | Tratamento |
|---|---|
| 400 / 422 | Confira campos, tipos e regras de negócio. Não repita o mesmo corpo sem correção. |
| 401 | Sessão expirada, credencial inválida ou autenticação ausente. |
| 403 | Origem, permissão, vendedor ou verificação de segurança não autorizados. |
| 404 | Recurso ou rota não encontrado; confira os identificadores. |
| 409 | Conflito de versão ou de idempotência; reconcilie o estado. |
| 429 | Limite de requisições atingido; reduza a frequência e respeite Retry-After quando presente. |
| 500 / falha de rede | Guarde o contexto; consulte o estado antes de repetir uma operação financeira. |
O erro inclui code, message e request_id; erros de validação podem incluir field_errors. Guarde request_id para rastrear o problema, sem registrar credenciais. As mensagens ajudam pessoas; use code para decisões da integração.
Não há promessa de paginação universal. Veja os parâmetros e formatos de cada endpoint. Algumas listagens retornam apenas os registros mais recentes.