Errors
Every failure is an EnginexError:
| Field | Content |
|---|---|
code | Gateway code (e.g. INSUFFICIENT_BALANCE) or SDK code (NETWORK_ERROR, TIMEOUT, ABORTED, VALIDATION_ERROR, CONFIGURATION_ERROR). |
status | HTTP status; 0 when there was no HTTP response (network, timeout, cancellation, validation, configuration). Exception: the UNAUTHENTICATED that the SDK itself throws before sending, when there is no session, comes with 401. |
message | Message from the gateway or the SDK. |
details | Raw map sent by the gateway, with the keys as they came over the wire (e.g. site_key in captcha_required), without conversion to camelCase. |
requestId | Give it to support to trace the request. |
retryAfter | Seconds until trying again (on 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 with status 0 means the app itself canceled the request (via signal), so it can normally be ignored. The gateway can also emit ABORTED with an HTTP status; in that case it is a business error from the server, not a cancellation.
isEnginexError works even if the app has two copies of the package installed.
The full list of known codes, with typical status and the meaning of each, is in Error codes. The EnginexErrorCode type also accepts new codes that the gateway may emit.
Typed details
By default details is unknown — the gateway's raw map, with no format guarantee. For the few codes with a known format (e.g. captcha_required), isEnginexError(e, code) narrows details automatically via ErrorDetailsMap:
if (isEnginexError(e, 'captcha_required')) {
e.details?.site_key // string | undefined, no cast
}The type of captcha_required is CaptchaRequiredDetails | undefined: the gateway may omit details, so TypeScript requires the ?. (and your code decides what to do without the site key).
To type the details of your own codes (e.g. an ad hoc code from your operator), extend ErrorDetailsMap through declaration merging:
declare module '@getenginex/sdk' {
interface ErrorDetailsMap {
my_code: { field: string }
}
}Serialization
EnginexError is serializable: JSON.stringify(e) uses toJSON() ({ name, code, message, status, details, requestId, retryAfter }), useful for structured logs, Sentry, or sending the error through postMessage/between a Web Worker and the page. To rebuild it on the other side, 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 also accepts an EnginexError (returns the same object) or any other value: without the { code, message } shape, it becomes UNKNOWN with the best possible message.
String(e) returns EnginexError [CODE]: message, useful in plain-text logs.