API Quirks & Compatibility
The live ZR Express API sometimes behaves differently from its own OpenAPI spec and docs. These are verified live and drive how the SDK (and your code) must build requests. Reading this page will save you from the common 400/403/500s.
This mirrors the drift register in
docs/API_REFERENCE.md §9. Rule: live behaviour wins.
At a glance
| # | Quirk | Impact |
|---|---|---|
| 9.1 | 401/403 have empty bodies | Don't assume a JSON error body |
| 9.2 | TerritoryResponse includes nameArabic live | Extra field, typed as optional |
| 9.3 | Supplier balance shape differs from spec | Read fields defensively |
| 9.4 | Webhook phone shape is PhoneDto, not {countryCode,number} | Permissive union |
| 9.5 | Server tolerates out-of-range paging | Validate client-side |
| 9.9 | getPortal not callable with an API key | Expect 403 |
| 9.10 | Webhook emission not synchronous/guaranteed | Don't assume instant delivery |
| 9.11 | supplier.get needs the id in the body too | Echo supplierId |
| 9.12 | Label-PDF format must be a bare string | 'A4'/'A6', not the object |
| 9.13 | Parcel create requires productId+sku, valid phone, hub for pickup | Most common 400 |
| 9.14 | reports/documents search blocked for API keys | 404/403 |
| 9.15 | Webhook create 500s if eventTypes omitted | Always send eventTypes |
9.1 — Empty-body 401 / 403
Auth failures return no JSON body: a missing/invalid API key is 401; a missing/invalid X-Tenant or an insufficient role is 403. The SDK maps these on status alone, so ZrExpressAuthError/ZrExpressForbiddenError still carry a useful message. (Some role-forbidden endpoints — §9.14 — do return a ProblemDetails.)
9.2 — nameArabic on territories
Live /territories/search items include a nameArabic field absent from the spec. The SDK types it as nameArabic?: string | null. Great for RTL displays.
9.3 — Supplier balance shape
GET /supplier-payment/supplier-balance returns, live: totalAmountPaid, totalAmountReadyToBePaid, totalAmountDelivered, totalAmountNotReadyCashed, totalAmountReadyToBeCashed — not the spec's totalAmountNotCashed/totalAmountCashed. The type is the union (all optional); read balance fields defensively.
9.4 — Webhook phone shape
The webhook guide shows phone as { countryCode, number }, but a captured live delivery serialized customer.phone as the REST PhoneDto ({ number1 }). ParcelWebhookDto keeps a permissive WebhookPhone union admitting both.
9.5 — Tolerant paging
pageNumber: 0 / pageSize: 0 returned 200 with defaults rather than 400. Don't rely on server-side validation for client bugs — validate paging yourself.
9.9 — getPortal denied to API keys
zr.webhookEndpoints.getPortal() returns 403 DenyApiKey.ApiKeyNotAllowed ("This endpoint is not accessible via API") — the embedded Svix consumer portal is reachable only via the portal's own JWT session, not X-Api-Key.
9.10 — Webhook emission is not guaranteed-immediate
Transitioning a parcel through early workflow states did not always produce an endpoint delivery within the observation window. Prefer webhooks for state tracking, but do not assume synchronous delivery of every transition; de-dupe by svix-id and reconcile.
9.11 — supplier.get echoes the id in the body
POST /supplier/{supplierId} returns 400 Validation failed when the id is only in the path. Repeat it in the body:
const supplier = await zr.supplier.get(supplierId, {
supplierId, // required in the body too
includeServices: true,
});Same "id echoed in the body" shape as UpdateParcelStateRequest.parcelId.
9.12 — Label-PDF format is a bare string
The generated type models format as PdfLabelFormat { value } with a readOnly value, so format: { value: 'A4' } — or even {} — is rejected with 400. The live API wants a plain string. Since SDK 0.1.1 the format type accepts it directly:
await zr.labels.generateMultiplePdf({
trackingNumbers: ['ZR-123'],
format: 'A4', // or 'A6', or omit for the server default
});9.13 — Parcel create requirements
The single most common 400 (General.Validation). A valid CreateParcelRequest needs:
customer.customerId— a real GUID.customer.phone.number1— present and a valid international number.- at least one
orderedProducts[]carrying both a validproductId(GUID) and a non-emptyproductSku(the sku isn't cross-checked — any non-empty string works).stockType: 'none'is accepted. - for
deliveryType: 'pickup-point', ahubId—'home'needs none.
Note products.search can return 0 while parcels still reference real product ids, so you may have to resolve a productId from an existing parcel's orderedProducts rather than the catalog. See the full verified create example.
9.14 — reports/documents search blocked for API keys
zr.reports.search → 404 (/reports/search not served for API-key callers). zr.documents.search → 403 DenyApiKey.ApiKeyNotAllowed. Both methods exist (a portal/JWT session may reach them); with an API key, handle the errors. See Reports & Documents.
9.15 — Webhook create needs eventTypes
The docs say "omit eventTypes for all events", but omitting it returns 500. Always send a non-empty array — to subscribe to everything, send the full ZR_WEBHOOK_EVENTS:
import { ZR_WEBHOOK_EVENTS } from '@terminaldz/zrexpress-sdk/webhooks';
await zr.webhookEndpoints.create({
url: 'https://your.app/webhooks/zr',
eventTypes: [...ZR_WEBHOOK_EVENTS], // never omit
});