Erros e respostas
Erros seguem a RFC 7807 (Problem Details for HTTP APIs). O corpo da resposta inclui sempre type, title, status e detail.
Códigos comuns
| Parâmetro | Tipo | Descrição |
|---|---|---|
| 400 | Bad Request | Payload mal formatado ou parâmetros inválidos. |
| 401 | Unauthorized | Token ausente, expirado ou inválido. |
| 403 | Forbidden | Token válido, mas sem permissão para o recurso. |
| 404 | Not Found | Recurso inexistente. |
| 409 | Conflict | Conflito de estado (ex.: txid duplicado). |
| 422 | Unprocessable Entity | Validação de negócio falhou (ex.: saldo insuficiente). |
| 429 | Too Many Requests | Limite de taxa excedido. Aguarde e refaça com backoff. |
| 500 | Internal Server Error | Erro inesperado. Pode ser repetido com Idempotency-Key. |
Exemplo de resposta de erro
{
"type": "https://docs.bsfinance.tech/errors/insufficient-funds",
"title": "Saldo insuficiente",
"status": 422,
"detail": "A conta acc_9f2b3c não possui saldo suficiente para a operação solicitada.",
"violacoes": [
{ "razao": "Saldo disponível: R$ 12,40", "propriedade": "amount" }
]
}