The backend commonly returns an error envelope like this; older routes, validation errors and upstream proxies can return different JSON or text:
Video tutorials for this topic
{
"code": "missing_orgid",
"statusCode": 400,
"error": "Organization ID is required. Pass orgid as a header, query param, or body field.",
"path": "/",
"method": "GET",
"timeStamp": "2026-09-11T09:16:21.511Z"
}Branch on code. It is stable. error is written for a human and will be reworded.
try {
await appmint('client/affiliate/me', { customerToken });
} catch (err) {
if (err.code === 'missing_authorization_header') return redirectToSignIn();
if (err.status === 429) return retryAfterBackoff();
throw err;
}Codes worth handling
| Code | Status | Meaning | What to do |
|---|---|---|---|
missing_orgid | 400 | No tenant on the request | Send orgid. A configuration bug, not a user error |
missing_authorization_header | 401 | Customer route without a token | Sign the customer in |
token_expired, invalid_token, auth_error or absent | 401 | Application or customer authentication failed | The JS SDK renews the app token once on the server; diagnose customer session separately |
| — | 403 | Authenticated but not permitted | Do not retry |
| — | 404 | No such record | Distinguish "gone" from "never existed" before deleting local state |
| — | 409 | Conflict — usually a uniqueness clash | Surface the field; a referral code taken mid-write lands here |
| — | 422 | Validation failed | Show the message; the body says which field |
| — | 429 | Rate limited | Back off, honour Retry-After |
| — | 5xx | Server fault | Retry idempotent reads; never blind-retry a payment |
Validation is strict
The global pipe runs with forbidNonWhitelisted: true, so an undeclared property rejects the whole request rather than being ignored.
This bites on read-modify-write: fetch a record, change one field, send it back, and the platform fields (sk, pk, createdate, version) plus computed ones (calculatedPrice) are not accepted by the write DTO.
// Fails with 400
const { data: product } = await appmint(`storefront/product/${sku}`);
product.data.price = 42;
await appmint('…', { method: 'POST', body: product });
// Works — send only what the write accepts
await appmint('…', { method: 'POST', body: { sku, price: 42 } });enableImplicitConversion does coerce "5" to 5 where the DTO says number, so numeric strings from form inputs are fine.
Failures that are not errors
Some outcomes return 200 with a verdict in the body. Check the field, not the status.
A bad coupon — the cart still prices, the total is unchanged:
{ "valid": false, "reason": "not_found", "message": "Discount code not found", "total": 1049.25 }An unservable destination — served: false is the honest answer, never a guessed rate:
{ "served": false, "options": [], "currency": "USD" }Priced but unquotable — somewhere is covered, but not right now:
{
"served": true,
"options": [],
"problems": [
{ "config": "live", "reason": "live: Cannot calculate shipping: \"SKU1\" is missing parcel dimensions (length/width/height). Set dimensions on the product or use a fixed shipping rate." }
]
}problems[] names the offending configuration and why. Show it — "we can't ship there" and "this product has no dimensions set" need different actions from different people.
Proxy your errors faithfully
If you put your own server in front (and you should — see The server proxy), forward the upstream status:
if (axiosError.response) {
return NextResponse.json(
{ error: axiosError.response.data, status: axiosError.response.status },
{ status: axiosError.response.status },
);
}Collapsing everything into 500 turns a missing record into an outage and hides the 422 message the user needed to read.
JavaScript transport failures
AppmintError contains status, optional code, and body. AppmintNetworkError extends it with status 0; return a valid HTTP status such as 503 from your own route. The SDK parses JSON when possible, falls back to text, and does not expose response headers. Do not assume code is always present or that every 400 comes from a typed DTO.
Application-key exchange errors are swallowed by the current SDK, which then sends the resource request without an app token. A successful public catalog call is therefore not proof that application authentication succeeded. A resource 401 triggers one app-token renewal/replay, including POST; it does not refresh the customer session. Avoid an additional blanket retry loop around payment or mutation calls.
Keep visitor sessions on network/503 failures. Report the unavailable dependency through your health/error handling instead of replacing a failed request with an empty successful response. Inspect served, options, and problems together for shipping failures; do not infer free shipping from an empty list.
