Errores
Toda falla es un EnginexError:
| Campo | Contenido |
|---|---|
code | Código del gateway (p. ej., INSUFFICIENT_BALANCE) o del SDK (NETWORK_ERROR, TIMEOUT, ABORTED, VALIDATION_ERROR, CONFIGURATION_ERROR). |
status | Status HTTP; 0 cuando no hubo respuesta HTTP (red, timeout, cancelación, validación, configuración). Excepción: el UNAUTHENTICATED que el propio SDK lanza antes de enviar, cuando no hay sesión, viene con 401. |
message | Mensaje del gateway o del SDK. |
details | Mapa crudo enviado por el gateway, con las claves como llegaron por la red (p. ej., site_key en captcha_required), sin conversión a camelCase. |
requestId | Infórmalo a soporte para rastrear el request. |
retryAfter | Segundos hasta volver a intentar (en 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 con status 0 significa que la propia app canceló el request (vía signal), así que normalmente se puede ignorar. El gateway también puede emitir ABORTED con un status HTTP; en ese caso es un error de negocio del servidor, no una cancelación.
isEnginexError funciona incluso si la app tiene dos copias del paquete instaladas.
La lista completa de códigos conocidos, con status típico y el significado de cada uno, está en Códigos de error. El tipo EnginexErrorCode también acepta códigos nuevos que el gateway llegue a emitir.
details tipado
Por defecto details es unknown — el mapa crudo del gateway, sin garantía de formato. Para los pocos códigos con un formato conocido (p. ej., captcha_required), isEnginexError(e, code) estrecha details automáticamente vía ErrorDetailsMap:
if (isEnginexError(e, 'captcha_required')) {
e.details?.site_key // string | undefined, no cast
}El tipo de captcha_required es CaptchaRequiredDetails | undefined: el gateway puede omitir details, así que TypeScript exige el ?. (y tu código decide qué hacer sin la site key).
Para tipar el details de tus propios códigos (p. ej., un código ad hoc de tu operador), extiende ErrorDetailsMap por declaration merging:
declare module '@getenginex/sdk' {
interface ErrorDetailsMap {
my_code: { field: string }
}
}Serialización
EnginexError es serializable: JSON.stringify(e) usa toJSON() ({ name, code, message, status, details, requestId, retryAfter }), útil para logs estructurados, Sentry o enviar el error por postMessage/entre un Web Worker y la página. Para reconstruirlo al otro lado, usa 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 también acepta un EnginexError (devuelve el mismo objeto) o cualquier otro valor: sin el formato { code, message }, se convierte en UNKNOWN con el mejor mensaje posible.
String(e) devuelve EnginexError [CODE]: mensaje, útil en logs de texto plano.