docs
/
Client Integration

Errors

The error envelope, the codes you must handle, and what each one actually means.

The backend commonly returns an error envelope like this; older routes, validation errors and upstream proxies can return different JSON or text:

{
  "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

CodeStatusMeaningWhat to do
missing_orgid400No tenant on the requestSend orgid. A configuration bug, not a user error
missing_authorization_header401Customer route without a tokenSign the customer in
token_expired, invalid_token, auth_error or absent401Application or customer authentication failedThe JS SDK renews the app token once on the server; diagnose customer session separately
—403Authenticated but not permittedDo not retry
—404No such recordDistinguish "gone" from "never existed" before deleting local state
—409Conflict — usually a uniqueness clashSurface the field; a referral code taken mid-write lands here
—422Validation failedShow the message; the body says which field
—429Rate limitedBack off, honour Retry-After
—5xxServer faultRetry 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.