Skip to main content

SDK Error Handling

This guide covers how to catch and handle errors from the Orbitport SDK, interpret error codes, and configure retry behavior.

Catch SDK errors​

Wrap your SDK calls in a try/catch block and check for OrbitportSDKError:

import {
  OrbitportSDK,
  OrbitportSDKError,
  ERROR_CODES,
} from "@spacecomputer-io/orbitport-sdk-ts";

const sdk = new OrbitportSDK({ config: {} });

try {
  const result = await sdk.ctrng.random();
  console.log(result.data.data);
} catch (error) {
  if (error instanceof OrbitportSDKError) {
    console.log("Error code:", error.code);
    console.log("Error message:", error.message);
  }
}

Common error codes​

CodeMeaning
AUTH_FAILEDAuthentication failed. Check your client ID and secret.
NETWORK_ERRORThe request could not reach the API or IPFS gateway.

Use error.code to branch on specific failure modes:

try {
  const result = await sdk.ctrng.random();
} catch (error) {
  if (error instanceof OrbitportSDKError) {
    switch (error.code) {
      case "AUTH_FAILED":
        console.error("Invalid credentials -- check your client ID and secret.");
        break;
      case "NETWORK_ERROR":
        console.error("Network issue -- check your connection.");
        break;
      default:
        console.error(`Unexpected error [${error.code}]: ${error.message}`);
    }
  }
}

Configure retry behavior​

The SDK retries failed requests automatically. You can tune this in the config:

const sdk = new OrbitportSDK({
  config: {
    retryAttempts: 5,   // Number of retries (default: 3)
    retryDelay: 2000,   // Delay between retries in ms (default: 1000)
  },
});

Automatic IPFS fallback​

When API credentials are provided, the SDK tries the API first. If the API request fails, it automatically falls back to the IPFS beacon. This means transient API errors may be transparent to your application -- you still get a cTRNG value, just from a different source.

Check result.data.src to see which source was used:

const result = await sdk.ctrng.random();
if (result.data.src === "ipfs") {
  console.log("Value came from IPFS fallback");
}

Best practices​

  1. Always wrap calls in try/catch. Even with retries and fallback, some errors (like invalid configuration) are not recoverable.
  2. Check error.code for specific handling. Avoid matching on error messages, which may change between SDK versions.
  3. Tune retries for your use case. Lower retryAttempts for latency-sensitive applications; raise it for background jobs.

Next steps​