Error Handling

Error shape

SDK methods throw RisingTideError on failure. The class shape:

class RisingTideError extends Error {
  code: string;         // Machine-readable error code (e.g., "NOT_FOUND")
  statusCode?: number;  // HTTP status code
  details?: unknown;    // Optional additional context
}

Catching errors

import { RisingTideError } from "@rising-tide/sdk";

try {
  const product = await rtClient.smartProducts.getById(123);
} catch (err) {
  if (err instanceof RisingTideError) {
    console.log(err.code);       // "NOT_FOUND"
    console.log(err.statusCode); // 404
  }
}

React Query error handling

React hooks are not part of the headless SDK - they ship from @rising-tide/ui. The hooks surface errors via the error property, and the error is the same RisingTideError (imported from @rising-tide/sdk):

import { RisingTideError } from "@rising-tide/sdk";

const { data, error } = useSmartProduct(productId);

if (error instanceof RisingTideError && error.code === "NOT_FOUND") {
  return <NotFoundPage />;
}

Common error codes

See API Errors for the full list of error codes.

Rate limits

A 429 is thrown as RateLimitError, a subclass of RisingTideError with code: "RATE_LIMITED" and statusCode: 429. It carries the server's back-off signal as fields: retryAfterSeconds (null when the header is absent), limit and remaining. The SDK never waits and retries for you - a Retry-After can be a full window, so the caller decides whether to wait or to tell the person.

import { RateLimitError } from "@rising-tide/sdk";

try {
  await rtClient.invites.claim(code);
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(err.retryAfterSeconds);
  }
}

Network errors

A request that never reaches the API (timeout, DNS failure, no connection) is thrown as a RisingTideError with code: "NETWORK_ERROR" and no statusCode. A non-2xx response whose body carries no structured error is thrown with code: "HTTP_ERROR". Branch on code and statusCode rather than on the message.