Tratamento de erros
Toda falha da API vira uma exceção tipada que estende SelectwinError. Decida o fluxo pelo tipo da exceção (ou por error.code), nunca pela mensagem — mensagens mudam, tipos e códigos não.
Toda falha da API vira uma exceção tipada que estende SelectwinError. Decida o fluxo pelo tipo da exceção (ou por error.code), nunca pela mensagem — mensagens mudam, tipos e códigos não.
A hierarquia
Todas as classes são exportadas do pacote e estendem SelectwinError, que carrega:
class SelectwinError extends Error {
code?: string; // código estável do erro (ex.: "card_declined")
statusCode?: number; // status HTTP
requestId?: string; // id da requisição — cite no suporte
raw?: unknown; // corpo bruto da resposta
}| Classe | Status | Campos extras |
|---|---|---|
AuthenticationError | 401 | — |
CardError | 402 | displayMessage, reversible |
PermissionError | 403 | — |
NotFoundError | 404 | — |
ValidationError | 400 e 422 | params (lista de campos inválidos) |
ConflictError | 409 | — |
RateLimitError | 429 | retryAfter (segundos) |
ApiError | 5xx / não classificado | — |
ApiConnectionError | falha de rede / timeout | raw |
SignatureVerificationError | — | verificação de webhook (ver Webhooks) |
Tratando por tipo
import {
Selectwin,
SelectwinError,
CardError,
ValidationError,
RateLimitError,
} from '@selectwin/sdk';
const sw = new Selectwin(process.env.SELECTWIN_API_KEY!);
try {
await sw.transactions.create({ /* … */ });
} catch (e) {
if (e instanceof CardError) {
// 402 — mostre e.displayMessage ao cliente; e.reversible indica se vale retentar
console.error(e.displayMessage, e.reversible);
} else if (e instanceof ValidationError) {
// 422 — e.params lista cada campo com problema
for (const p of e.params ?? []) console.error(p.field, p.message);
} else if (e instanceof RateLimitError) {
// 429 — espere e.retryAfter segundos antes de tentar de novo
console.error('aguarde', e.retryAfter, 's');
} else if (e instanceof SelectwinError) {
console.error(e.code, e.statusCode, e.requestId);
} else {
throw e; // erro que não veio da Selectwin
}
}Retentativas automáticas
O cliente já retenta automaticamente falhas transitórias — 429, 5xx e erros de rede — com backoff. O padrão é maxRetries: 2; ajuste na criação do cliente:
const sw = new Selectwin(key, { maxRetries: 4, timeoutMs: 30_000 });Como cada mutação envia um X-Idempotency-Key automático, essas retentativas são seguras — a API não duplica a operação. Para reusar sua própria chave entre execuções (retry de um pedido, por exemplo), passe idempotencyKey nas opções da chamada. Ver Idempotência.
Próximos passos
- Webhooks — verificar assinaturas e tipar eventos.
- Paginação — iterar listas grandes.
- Códigos de erro · Recusas de pagamento.
How is this guide?