Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

Erros ​

Toda falha é um EnginexError:

CampoConteúdo
codeCódigo do gateway (ex.: INSUFFICIENT_BALANCE) ou do SDK (NETWORK_ERROR, TIMEOUT, ABORTED, VALIDATION_ERROR, CONFIGURATION_ERROR).
statusStatus 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.
messageMensagem do gateway ou do SDK.
detailsMapa cru enviado pelo gateway, com as chaves como vieram no fio (ex.: site_key em captcha_required), sem conversão para camelCase.
requestIdInforme ao suporte para rastrear o request.
retryAfterSegundos até tentar de novo (em 429).
ts
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:

ts
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:

ts
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:

ts
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 usual

EnginexError.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.