Erros
Toda falha é um EnginexError:
| Campo | Conteúdo |
|---|---|
code | Código do gateway (ex.: INSUFFICIENT_BALANCE) ou do SDK (NETWORK_ERROR, TIMEOUT, ABORTED, VALIDATION_ERROR, CONFIGURATION_ERROR). |
status | Status HTTP; 0 quando não houve resposta HTTP (rede, timeout, cancelamento, validação, configuração). Exceção: o UNAUTHENTICATED que o próprio SDK lança antes de enviar, quando não há sessão, vem com 401. |
message | Mensagem do gateway ou do SDK. |
details | Mapa cru enviado pelo gateway, com as chaves como vieram no fio (ex.: site_key em captcha_required), sem conversão para camelCase. |
requestId | Informe ao suporte para rastrear o request. |
retryAfter | Segundos até tentar de novo (em 429). |
import { isEnginexError } from '@getenginex/sdk'
try {
await enginex.auth.login({ email, password })
} catch (e) {
if (isEnginexError(e, 'INVALID_CREDENTIALS')) return showError('Incorrect email or password')
if (isEnginexError(e, 'ACCOUNT_LOCKED')) return showError('Account temporarily locked')
if (isEnginexError(e, 'NETWORK_ERROR') || isEnginexError(e, 'TIMEOUT')) return showError('No connection')
throw e
}ABORTED com status 0 significa que o próprio app cancelou o request (via signal), então normalmente pode ser ignorado. O gateway também pode emitir ABORTED com um status HTTP; nesse caso é um erro de negócio do servidor, não um cancelamento.
isEnginexError funciona mesmo se o app tiver duas cópias do pacote instaladas.
A lista completa de códigos conhecidos, com status típico e o significado de cada um, está em Códigos de erro. O tipo EnginexErrorCode também aceita códigos novos que o gateway venha a emitir.
details tipado
Por padrão details é unknown — o mapa cru do gateway, sem garantia de formato. Para os poucos códigos com um formato conhecido (ex.: captcha_required), isEnginexError(e, code) estreita details automaticamente via ErrorDetailsMap:
if (isEnginexError(e, 'captcha_required')) {
e.details?.site_key // string | undefined, no cast
}O tipo de captcha_required é CaptchaRequiredDetails | undefined: o gateway pode omitir o details, então o TypeScript exige o ?. (e o seu código decide o que fazer sem a site key).
Para tipar o details dos seus próprios códigos (ex.: um código ad hoc do seu operador), estenda ErrorDetailsMap por declaration merging:
declare module '@getenginex/sdk' {
interface ErrorDetailsMap {
my_code: { field: string }
}
}Serialização
EnginexError é serializável: JSON.stringify(e) usa toJSON() ({ name, code, message, status, details, requestId, retryAfter }), útil para logs estruturados, Sentry ou mandar o erro por postMessage/entre um Web Worker e a página. Para reconstruir do outro lado, use EnginexError.from:
const json = JSON.stringify(error)
// ...crosses a worker, a log, a queue...
const revived = EnginexError.from(JSON.parse(json))
isEnginexError(revived, 'INVALID_CREDENTIALS') // works as usualEnginexError.from também aceita um EnginexError (devolve o mesmo objeto) ou qualquer outro valor: sem o formato { code, message }, vira UNKNOWN com a melhor mensagem possível.
String(e) devolve EnginexError [CODE]: mensagem, útil em logs de texto simples.