---
title: "Tratamento de erros"
url: "https://devcenter.stone.com.br/foundations-errors"
image: "https://devcenter.stone.com.br/_og/d/c_Ocean.takumi,title_Tratamento+de+erros,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMzMEE2NkQifX19,p_Ii9mb3VuZGF0aW9ucy1lcnJvcnMi,s_81uLohoGDss47V1b.png"
---

## **Tratamento de erros**

RFC 7807 Problem Details — formato único.

# Erros

Seguimos **RFC 7807 Problem Details**. Toda resposta de erro tem o mesmo shape:

```json
{
  "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        |

## [Veja também](#veja-também)

[**Autenticação**OAuth2, API Key e mTLS — três modos, mesmas credenciais.](https://devcenter.stone.com.br/foundations-auth)[**Ambientes**Sandbox vs produção, dados de teste, migração.](https://devcenter.stone.com.br/foundations-environments)[**Idempotência**Idempotency-Key em todas as escritas — sem duplicatas em retries.](https://devcenter.stone.com.br/foundations-idempotency)[**Foundations**Tudo que é compartilhado entre Checkout, Stone Online, Físico/TEF e Conta Stone.](https://devcenter.stone.com.br/foundations-overview)

Siga a Stone nas redes sociais

[](https://www.facebook.com/stonepagamentos/)[](https://x.com/sejastone/)[](https://www.instagram.com/stone/)[](https://br.linkedin.com/company/stone-co)[](https://www.youtube.com/channel/UCk4L4JykgoDkN8YeuxkNqIQ)

© Stone Instituição de Pagamento S.A. CNPJ 16.501.555/0001-57

Av. Rebouças, 2880, 4º andar, Pinheiros, CEP 05.402-500 – São Paulo/SP

Instituição de pagamento autorizada pelo Banco Central do Brasil, nas modalidades de credenciadora e emissora de moeda eletrônica.