Idempotência, paginação e erros
Idempotência
Todas as mutações financeiras exigem Idempotency-Key com 8 a 255 caracteres. Persista a chave junto da operação lógica e reutilize-a somente ao repetir a mesma operação com os mesmos parâmetros.
A chave é isolada por organização e operação antes de ser enviada ao Stripe. A retenção financeira segue a retenção do Stripe; não representa deduplicação permanente. Criação de conta usa uma reserva durável própria, descrita em Conta e onboarding.
Evite gerar uma nova chave a cada retry: isso pode criar operações distintas.
Paginação
Listas financeiras aceitam limit de 1 a 100 e starting_after, o ID do último item da página anterior.
GET /v2/organizations/{organizationId}/stripe/customers?limit=20&starting_after=cus_EXEMPLOA resposta contém data e has_more. Enquanto has_more for true, use o último ID de data como próximo cursor. Não use offset nem espere um campo total nessas listas.
Valores e identificadores
Valores monetários são inteiros na menor unidade da moeda: 1250 equivale a R$12,50 em brl. Códigos de moeda usam três letras minúsculas. Os identificadores e estados dos recursos são retornados pelo Stripe; não traduza IDs históricos para IDs Stripe.
Erros
O handler central retorna erros no formato abaixo; code, requestId e fields são opcionais. Trate o erro pelo code, que é estável, e não pela mensagem em error. Falhas de autenticação e de rate limit podem ter corpo diferente ou vazio.
{
"error": "Validation failed for: amount",
"code": "validation_failed",
"requestId": "IDENTIFICADOR_DA_REQUISICAO",
"fields": ["amount"]
}| HTTP | Situação | Tratamento |
|---|---|---|
| 400 | Regra de negócio ou parâmetros rejeitados pelo Stripe | Corrija a requisição |
| 401 | Credencial ausente, inválida ou expirada | Confira a credencial |
| 402 | Pagamento recusado pelo Stripe | Solicite revisão do meio de pagamento |
| 403 | Permissões insuficientes | Confira permissões e papel humano |
| 404 | Recurso ou organização não encontrado neste escopo | Confira organização e identificador |
| 409 | Idempotência conflitante, onboarding pendente, desconexão ou ambiente incompatível | Confira o estado e os parâmetros; peça revisão quando necessário |
| 422 | Validação de corpo, parâmetros ou cabeçalhos | Corrija os campos indicados |
| 429 | Limite de requisições | Reduza frequência e use espera progressiva |
| 500 | Falha interna | Correlacione o request ID com o suporte |
| 502 | Stripe indisponível ou configuração pendente | Confira configuração antes de tentar novamente |
| 503 | Stripe não configurado | Solicite configuração à equipe |
Ao repetir uma mutação após falha transitória, mantenha a mesma chave de idempotência. Não registre API keys, cookies, client_secret ou dados do pagador ao investigar erros.