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
| Error | When |
|---|---|
ZrExpressConfigError | Invalid client options / SDK misuse (thrown at construction). |
ZrExpressNetworkError | fetch failure / DNS / abort / timeout — carries .timedOut. |
ZrExpressAuthError | 401 — missing/invalid/expired API key (empty body). |
ZrExpressForbiddenError | 403 — missing/invalid X-Tenant or insufficient role. |
ZrExpressNotFoundError | 404. |
ZrExpressValidationError | 400 (non-bulk operations). |
ZrExpressRateLimitError | 429 — carries .retryAfterMs. |
ZrExpressServerError | 5xx. |
ZrExpressBulkError | Thrown only by assertBulkOk — carries .failures. |
ZrExpressWebhookVerificationError | Bad/tampered/stale signature or unknown payload. |
All HTTP errors are subclasses of ZrExpressApiError.
What an API error carries
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 */ }
}codeis theProblemDetails.title— a machine code likeParcelErrors.NotFoundorGeneral.Validation. Branch on it, not on the humandetail.requestIdis 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:
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.