Tratamento de erros
RFC 7807 Problem Details — formato único.
Erros
Seguimos RFC 7807 Problem Details. Toda resposta de erro tem o mesmo shape:
{
"type": "https://docs.stone.com.br/errors/card_declined",
"title": "Cartão recusado pelo emissor",
"status": 402,
"code": "card_declined",
"detail": "O emissor recusou a transação (motivo: 51 — saldo insuficiente).",
"request_id": "req_8K2x9Lp...",
"param": "payment.card.number"
}
| HTTP | Significado |
|---|---|
| 400 | Requisição malformada |
| 401 | Token inválido/expirado |
| 402 | Pagamento recusado (negócio) |
| 403 | Sem permissão (escopo) |
| 404 | Recurso não existe |
| 409 | Conflito (idempotência, estado inválido) |
| 422 | Validação semântica falhou |
| 429 | Rate limit |
| 5xx | Falha interna — retry com backoff |