Valide antes de enviar
Use os limites definidos no OpenAPI, sem criar um segundo contrato em sua aplicação. Na criação, external_id aceita até 128 caracteres; Idempotency-Key, até 180; metadata, até 8 KB. O prazo expires_in_minutes, quando informado, varia entre 5 e 129600 minutos. Ausência de um campo opcional não é o mesmo que enviar um valor arbitrário.
Países, locales, estados e códigos devem ser lidos da referência vigente. O idioma en do site, por exemplo, não autoriza substituir automaticamente um enum de API por esse mesmo valor.
Controle o comportamento do cliente
Defina timeouts de conexão e resposta. Limite concorrência, monitore sua fila e use repetição com espera progressiva quando a causa for transitória. Corrija erros de autenticação, permissão ou payload antes de repetir. Não faça consulta contínua sem intervalo para cada transação.
Este guia não publica uma quota universal de requisições ou um SLA. Confirme os limites operacionais e comerciais aplicáveis à sua integração com o time responsável.
Reduza o que precisa proteger
Envie apenas dados necessários ao processo e não utilize metadata como depósito de documentos, segredos ou payloads pessoais extensos. Evite logar o corpo completo das requisições. Proteja links de jornada e arquivos baixados da mesma forma que outros acessos sensíveis.
Combine webhooks com reconciliação, em vez de depender exclusivamente de polling frequente. Revise o checklist de produção para ligar essas práticas à sua operação.