Skip to content

Error Handling ​

Every error the SDK throws extends ZrExpressError, so you can catch broadly or narrow by class. Mapping is by HTTP status.

The taxonomy ​

ErrorWhen
ZrExpressConfigErrorInvalid client options / SDK misuse (thrown at construction).
ZrExpressNetworkErrorfetch failure / DNS / abort / timeout — carries .timedOut.
ZrExpressAuthError401 — missing/invalid/expired API key (empty body).
ZrExpressForbiddenError403 — missing/invalid X-Tenant or insufficient role.
ZrExpressNotFoundError404.
ZrExpressValidationError400 (non-bulk operations).
ZrExpressRateLimitError429 — carries .retryAfterMs.
ZrExpressServerError5xx.
ZrExpressBulkErrorThrown only by assertBulkOk — carries .failures.
ZrExpressWebhookVerificationErrorBad/tampered/stale signature or unknown payload.

All HTTP errors are subclasses of ZrExpressApiError.

What an API error carries ​

ts
import {
  ZrExpressApiError,
  ZrExpressNotFoundError,
  ZrExpressAuthError,
} from '@terminaldz/zrexpress-sdk';

try {
  await zr.parcels.get('does-not-exist');
} catch (err) {
  if (err instanceof ZrExpressApiError) {
    err.status;    // 404
    err.code;      // 'ParcelErrors.NotFound' — the ProblemDetails.title machine code
    err.detail;    // human message
    err.traceId;   // support correlation id
    err.requestId; // { method, path } — never headers or body
  }
  if (err instanceof ZrExpressNotFoundError) { /* narrow */ }
}
  • code is the ProblemDetails.title — a machine code like ParcelErrors.NotFound or General.Validation. Branch on it, not on the human detail.
  • requestId is deliberately just { method, path } — it never contains headers or the request body, so it can't leak the key.

Empty-body 401 / 403 ​

Auth failures arrive with no JSON body — a missing/invalid key is 401, a missing/invalid tenant or insufficient role is 403. The SDK's mapping does not assume a body, so these errors still carry a descriptive message even when code/detail/traceId are absent:

ts
try {
  await zr.users.getProfile();
} catch (err) {
  if (err instanceof ZrExpressAuthError) {
    // "Authentication failed (HTTP 401): missing or invalid API key — it may be expired…"
    console.error(err.message);
  }
}

Key expiry (max 365 days) is a real operational event — on a 401, suspect expiry/rotation first.

Retries & 429 ​

The transport retries 429/5xx/network on idempotent methods and search POSTs, honouring Retry-After, with exponential backoff + full jitter — see Configuration → Retry policy. 429 that survives all attempts surfaces as ZrExpressRateLimitError with .retryAfterMs. Parcel and webhook creation are never retried.

Redaction ​

Errors are part of the SDK's secret-hygiene guarantee: no error's message, serialized form, or requestId ever contains the API key. See Configuration → Redaction guarantee.

Released under the MIT License. Not affiliated with ZR Express.