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
| Class | When | Notes |
|---|---|---|
SuqoConfigError | Constructing 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 |
AuthenticationError | 401 | Key is missing, malformed, or inactive |
KycRequiredError | 403 with a status_code in the body | Seller hasn't completed KYC. Carries kycStatus (KYC_INCOMPLETE or KYC_VERIFICATION_PENDING) |
PermissionDeniedError | 403 with only detail in the body | The 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 |
ValidationError | 400 | See below — three different body shapes, normalized into one class |
NotFoundError | 404 | Resource doesn't exist, or doesn't belong to your account |
RateLimitError | 429 | Only from checkoutSessions.create() today. Carries retryAfter — see Rate limits |
ServerError | 5xx (and any unmapped status) | Unexpected failure on SUQO's side |
NetworkError | No response at all | Covers 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.
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": ["…"] }→fieldErrorspopulated. detail—{ "detail": "…" }→message,fieldErrorsempty.- A bare list —
["This is a one-time purchase, so there is nothing to cancel."]→ the messages becomemessage,fieldErrorsempty. Sent bycancel,resumeandrenew(no request body to key a field on), and bysubscriptions.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.