Idempotência e erros
Repita requisições com segurança e trate o envelope de erros.
Idempotência
Envie o header Idempotency-Key (string única) em criações e capturas. Repetir a mesma chave retorna o resultado original em vez de criar um recurso duplicado — seguro para retentar em timeouts.
Idempotency-Key: 5f3b0c2a-...Envelope de erros
Erros seguem um envelope estável:
{ "type": "invalid_request_error", "code": "amount_too_small", "message": "amount must be >= 100", "request_id": "req_..."}Use code para lógica e request_id ao abrir suporte. Os códigos HTTP seguem a semântica REST usual (400/401/404/409/422).