Errors

When Digize turns a call down, the platform paths and the API answer the same way: the error’s HTTP status and { "error": { "code", "message", "details" } }. The SDK throws that as a DigizeError, from every entry point, so one catch handles the site client, the API client and webhooks alike.

import { DigizeError, isDigizeError } from "@digize/sdk";

try {
  await digize.store.product("cold-brew");
} catch (error) {
  if (isDigizeError(error, "not_found")) {
    // show the 404 page
  } else if (error instanceof DigizeError && error.code === "rate_limited") {
    // try again after error.retryAfter seconds
  } else {
    throw error;
  }
}

DigizeError and isDigizeError are exported from @digize/sdk, @digize/sdk/api and @digize/sdk/webhooks, and they’re the same class in all three.

What it carries

Property
`code`	What went wrong, from the table below. Branch on this.
`message`	Written for people, such as `"That product isn't in the store."`. It can be shown as it is, but it may change: don’t match on it.
`status`	The HTTP status Digize answered with, or `0` when nothing answered (the network failed, the call timed out) or the SDK refused the call before sending it.
`details`	More about it, when the error has any, such as `details.available` for an item that’s run low at checkout.
`fields`	A message for each field that wasn’t valid, keyed by its name: `details.fields`, or `{}`.
`retryAfter`	Seconds to wait, from a `429`’s `retry-after`, or `null`.
`cause`	For `status` 0, the error `fetch` threw.

Codes

`code`	Status	Means
`invalid`	400 (also 405, 415, 422)	What was sent isn’t valid: a field (see `fields`), a query, an `Idempotency-Key` used with a different request.
`unauthorized`	401	No API key, or one that’s unknown, turned off or expired; a webhook signature that doesn’t check out.
`forbidden`	403	The key lacks the permission the operation needs, a workspace is read-only for an unpaid bill (`details.reason: "billing_read_only"`), or a Turnstile check didn’t pass.
`not_found`	404	Nothing has that id or slug, or there’s no such operation.
`conflict`	409	The change clashes with the record’s state, or a request with the same idempotency key is still running.
`too_large`	413	The body is over the limit: 256 KB for a form, 64 KB for a store call, 1 MB for the API.
`rate_limited`	429	Over a rate limit. The API client waits and tries again by itself first.
`unavailable`	503, 502, 504 or 0	Digize couldn’t take it just now, or couldn’t be reached.
`internal`	500	A bug on Digize’s side. The API client tries again first.

An answer that isn’t Digize’s JSON, such as a proxy’s error page or a site’s own 404 page where a platform path should be, gets the code its status means. The site client says so in the message: a /_platform/ call answered by the site itself usually means its Worker doesn’t pass the browser’s calls on with handlePlatform.

Where it isn’t thrown

forms.submit answers { ok: false, code, message, fields, error } instead of throwing, so a page can show the visitor what to fix. See Forms.
analytics.track and analytics.pageview never throw: they answer false when an event wasn’t taken.
verifyWebhook answers false; parseWebhook throws.