Erros

A Stater retorna respostas de erro com um corpo JSON consistente que descreve o problema. Sempre verifique o status HTTP antes de processar o body.

Formato

{"error": {  "code": "invalid_request",  "message": "O campo amountCents é obrigatório.",  "details": { "field": "amountCents" }}}

Códigos HTTP comuns

• 400 — requisição malformada ou validação de campo.
• 401 — autenticação ausente ou inválida.
• 403 — sem permissão para o recurso.
• 404 — recurso não encontrado.
• 409 — conflito (ex.: Idempotency-Key reutilizado com payload diferente).
• 422 — regra de negócio violada (saldo insuficiente, limite excedido).
• 429 — rate limit excedido. Veja Rate limits.
• 5xx — erro interno; o request pode ser reenviado com segurança usando idempotência.

Códigos de erro

• invalid_request — payload inválido.
• unauthorized — credenciais inválidas.
• forbidden — sem permissão.
• not_found — recurso não existe.
• conflict — conflito de idempotência ou estado.
• insufficient_funds — saldo insuficiente.
• limit_exceeded — limite por transação ou diário ultrapassado.
• rate_limited — muitas requisições.
• provider_error — falha no provedor Pix; consulte providerResponse quando disponível.