SUQODocs
User GuideAPI ReferenceSDKs
TypeScript SDK v2.0.0. This version is frozen and no longer updated. Read the latest (2.1.0).

Handle errors

The SuqoError hierarchy in the SUQO TypeScript SDK.

Every error the SDK throws is an instance of SuqoError. The base class itself is never thrown directly — always one of the subclasses below. Check instanceof, never the error's message string or the raw response shape — those aren't part of the contract and can change wording without notice.

import { SuqoError } from "@suqo/sdk";

try {
  await suqo.checkoutSessions.create({ /* ... */ });
} catch (err) {
  if (err instanceof SuqoError) {
    console.error(err.name, err.message, err.status);
  }
}

The hierarchy

ClassWhenNotes
SuqoConfigErrorConstructing SuqoClient with a malformed key or a baseUrl that disagrees with it; or passing an empty, "." or ".." id to a method that puts the id in the URL path (retrieve, update, cancel, resume, and the webhook methods, which also reject "secret")Thrown before any request — synchronously from the constructor, as a rejected promise from a method call. See Configure the client. renew() and updateBillingCycle() send the id in the body, so the API validates it instead
AuthenticationError401Key is missing, malformed, or inactive
KycRequiredError403 with a status_code in the bodySeller hasn't completed KYC. Carries kycStatus (KYC_INCOMPLETE or KYC_VERIFICATION_PENDING)
PermissionDeniedError403 with only detail in the bodyThe key may not perform this action for a reason other than KYC — e.g. it doesn't belong to the account. New in 2.0.0
ValidationError400See below — three different body shapes, normalized into one class
NotFoundError404Resource doesn't exist, or doesn't belong to your account
RateLimitError429Only from checkoutSessions.create() today. Carries retryAfter — see Rate limits
ServerError5xx (and any unmapped status)Unexpected failure on SUQO's side
NetworkErrorNo response at allCovers both a genuine network failure and a timeout — there's no separate timeout class

Every subclass carries whatever the base class does:

interface SuqoErrorOptions {
  status?: number; // HTTP status, if there was a response
  rawBody?: unknown; // the raw parsed response body, if any
  requestId?: string; // SUQO's request id for this call, if the response included one
}

Two kinds of 403

A 403 is told apart by its body, never the status alone:

  • KYC not cleared — { "status_code": "KYC_VERIFICATION_PENDING", "message": "…" } → KycRequiredError. Resolved in the seller dashboard, not through the API.
  • Anything else — { "detail": "You do not have permission to perform this action." } → PermissionDeniedError.
Changed in 2.0.0. In 1.x every 403 was a KycRequiredError. If you catch KycRequiredError to prompt the seller to finish KYC, that's still right — it just no longer fires for permission problems that KYC wouldn't fix.

KYC is never enforced on the sandbox, and products.list() and every webhooks management method work before KYC on live too — on those, only PermissionDeniedError can occur.

ValidationError — three wire shapes, one class

A 400 comes back in one of three shapes on the wire; the SDK normalizes them so you only ever need instanceof ValidationError, never a shape check of your own:

  • Field-keyed — { "phone": ["…"] } → fieldErrors populated.
  • detail — { "detail": "…" } → message, fieldErrors empty.
  • A bare list — ["This is a one-time purchase, so there is nothing to cancel."] → the messages become message, fieldErrors empty. Sent by cancel, resume and renew (no request body to key a field on), and by subscriptions.create()'s one-subscription-per-product error.
import { ValidationError } from "@suqo/sdk";

try {
  await suqo.subscriptions.create({ /* ... */ });
} catch (err) {
  if (err instanceof ValidationError) {
    if (Object.keys(err.fieldErrors).length > 0) {
      // field-keyed body — e.g. { phone: ["This field is required."] }
      console.error(err.fieldErrors);
    } else {
      // a detail-shaped or bare-list body instead — e.g. the one-subscription-per-product case
      console.error(err.message);
    }
  }
}

fieldErrors is always a plain object (never undefined) — empty when the failure used the detail or bare-list shape instead. Nested validation (e.g. on subscriptions.create()'s customer payload) comes through as dot-path keys like customer.phone, already renamed from the wire's client.phone.

Rate limits

The API rate-limits one endpoint: checkoutSessions.create(), 20 sessions a minute per account. Every other call is unlimited. Over the limit it throws RateLimitError, whose retryAfter is the suggested wait in milliseconds — taken from a Retry-After header when one is present, otherwise parsed from the wait the API writes into its message ("…Expected available in 41 seconds."), and capped at 60 seconds.

import { RateLimitError } from "@suqo/sdk";

try {
  await suqo.checkoutSessions.create({ returnUrl, items });
} catch (err) {
  if (err instanceof RateLimitError) {
    await new Promise((resolve) => setTimeout(resolve, err.retryAfter ?? 60_000));
    // …then retry, or tell the buyer to try again shortly
  } else {
    throw err;
  }
}

Writes aren't automatically retried

Reads (list, retrieve, retrieveSecret) retry on NetworkError, 429, and 5xx with backoff. Writes — every POST, PATCH, PUT and DELETE: create, update, replace, delete, cancel, updateBillingCycle, resume, renew, testDelivery — never retry automatically. A blindly-retried write could double-act (e.g. a second checkout session or subscription) since the API has no idempotency-key support yet. See Idempotency for what changes once it does.

On this page