SDK errors

All SDK errors extend StrentError, while each failure boundary has a more specific class.

With the default cache, eligible availability errors can produce a saved positive or whole list instead of throwing, with a warning for each fallback. These classes still reach your catch when there is no eligible saved answer, caching is disabled, or the error does not allow fallback. See the cache rules →

Class	Meaning
StrentApiError	Strent returned a structured non-2xx API response
StrentRateLimitError	A 429 response, with retryAfterSeconds when supplied
StrentNetworkError	The request or response body could not be transported
StrentTimeoutError	The configured SDK timeout elapsed
StrentAbortError	The caller’s AbortSignal canceled the request
StrentResponseError	A successful response did not match the SDK contract

Inspect an API error

import { StrentApiError, StrentRateLimitError } from "@strent-dev/node";

try {
  await strent.activeItems.list({ customer: "cus_123" });
} catch (error) {
  if (error instanceof StrentRateLimitError) {
    logger.warn({
      requestId: error.requestId,
      retryAfterSeconds: error.retryAfterSeconds,
    });
    throw error;
  }

  if (error instanceof StrentApiError) {
    logger.error({
      status: error.status,
      code: error.code,
      requestId: error.requestId,
    });
  }

  throw error;
}

details may contain structured context for a particular API error. Treat it as diagnostic data rather than a stable application decision interface unless the endpoint contract documents a field explicitly.

Common API codes

Code	Meaning
VALIDATION_FAILED	Headers or request data are invalid
INVALID_AUTH_HEADER	Bearer authentication is missing or malformed
API_KEY_INVALID	No valid project key matches the secret
API_KEY_REVOKED	The project key is no longer active
RATE_LIMIT_EXCEEDED	The applicable request budget was exceeded
CUSTOMER_STATE_NOT_READY	Customer projection cannot answer yet
INTERNAL_ERROR	Strent could not complete the request

Newer API versions can add codes that an installed SDK version does not list. Handle a code you do not recognize by its status.

Do not show raw internal messages to end users. Preserve requestId in logs so operators can correlate the application failure with Strent.