Error codes & SDK exceptions

On failure, the SDK throws GStableError or a subclass. Use isGStableError(err) for type narrowing.

Base class

Property	Meaning
code	Numeric business or transport code; -1 often means network error before HTTP response.
message	Human-readable; do not rely on exact English strings for branching.

createTypedApiError

When the API returns an envelope with code !== 0, the HTTP layer calls createTypedApiError(code, message):

Condition	Thrown type
Product-range codes 100301–100306	GStableProductError (productErrorCode duplicates code)
Known common / validation codes (400XXX in SDK constants)	GStableCommonError
Known platform codes (900XXX / 999999)	GStablePlatformError
Otherwise	GStableError

Product codes (ProductErrorCodes)

Constant	Value	Typical meaning
NOT_FOUND	100301	Product ID does not exist.
PARTIAL_MISSING	100302	Batch: some IDs missing.
PARTIALLY_UNAVAILABLE	100303	Batch: some not usable.
NOT_ACTIVE	100304	Not active for link/session use.
HAS_BEEN_USED	100305	Blocked mutation due to usage.
HAS_BEEN_REMOVED	100306	Logically deleted.

Use isProductErrorCode(code), ProductErrorMessages (reference text only).

Common codes (CommonErrorCodes)

Constant	Value
INVALID_FIELD_FORMAT	400101
UNSUPPORTED_CURRENCY	400201
UNSUPPORTED_CHANNEL	400202
SETTLEMENT_CAPABILITIES_NOT_FOUND	400203
STAT_NOT_FOUND	400301

Platform codes (PlatformErrorCodes)

Constant	Value
TOO_MANY_REQUESTS	900101
FAILED_TO_CREATE_RECORD	900201
FAILED_TO_UPDATE_RECORD	900202
FAILED_TO_QUERY_RECORD	900203
IMAGE_PROCESSING_FAILED	900301
INTERNAL_SYSTEM_ERROR	999999

HTTP / transport edge cases

• Non-JSON body (HTML, WAF, proxy) → GStableError with descriptive message (403/401 helpers in SDK).
• Invalid envelope on HTTP 200 → GStableError.

Official taxonomy

Full, authoritative tables live under API overview → Errors on docs.gstable.io.

Example — branch on product errors

import {
  GStableClient,
  isGStableProductError,
  ProductErrorCodes,
} from 'gstable-js';

const client = new GStableClient({ apiKey: process.env.GSTABLE_API_KEY });

try {
  await client.product.remove('prod_xxx');
} catch (e) {
  if (isGStableProductError(e) && e.code === ProductErrorCodes.HAS_BEEN_USED) {
    // handle “in use”
  }
  throw e;
}