Skip to main content
Every error thrown by the SW Combine SDK is an instance of SWCError — a typed error class that carries the HTTP status code, a human-readable message, an error type string, and a retryable flag. Checking instanceof SWCError lets you distinguish SDK errors from unexpected runtime exceptions and handle them precisely.

​
Catching errors

Wrap any SDK call in a try/catch block and check instanceof SWCError to access the structured error details: 
import { SWCombine, SWCError } from 'swcombine-sdk';

const client = new SWCombine({ token: process.env.SWC_ACCESS_TOKEN! });

try {
  const character = await client.character.get({ uid: '1:99999' });
} catch (error) {
  if (error instanceof SWCError) {
    console.log(error.statusCode); // e.g. 404
    console.log(error.message);    // e.g. "Character not found"
    console.log(error.type);       // e.g. "not_found"
    console.log(error.retryable);  // false for 404
  } else {
    // Unexpected non-SDK error
    throw error;
  }
}

​
SWCError properties

​
statusCode
number
required
The HTTP status code returned by the API (e.g. 401, 404, 429, 500). For network-level failures where no HTTP response was received, this may be 0.
​
message
string
required
A human-readable description of what went wrong.
​
type
string
required
A stable string identifier for the error category. One of: not_found, unauthorized, auth, validation, network, server.
​
retryable
boolean
required
true when the SDK considers this error safe to retry automatically. Network errors, 5xx server errors, and rate limit responses (429) are retryable. Client errors like 404 and 401 are not.
​
response
object
The raw API response object, when one was received. Useful for inspecting response headers or the full error body from the server.

​
Error types

The requested resource does not exist. This is not retryable — the item you’re looking for isn’t there.
if (error.type === 'not_found') {
  console.log('Resource does not exist:', error.message);
}
Your access token is missing, expired, or does not have the required OAuth scope. This is not retryable. In token-only mode, you must supply a fresh token manually. In full OAuth mode, the SDK refreshes the token automatically before retrying.
if (error.type === 'unauthorized') {
  console.log('Check your token or required scopes:', error.message);
}
An error occurred during the OAuth authorization flow (e.g. an invalid authorization code or a failed token exchange). This is not retryable.
if (error.type === 'auth') {
  console.log('OAuth flow failed:', error.message);
}
The request was malformed or a required parameter was missing or invalid. Fix the input before retrying — this error is not retryable.
if (error.type === 'validation') {
  console.log('Invalid request parameters:', error.message);
}
A network-level failure occurred before a response was received: DNS resolution failed, the connection timed out, or the connection was reset. The SDK retries these automatically with exponential backoff.
if (error.type === 'network') {
  console.log('Network failure, SDK will retry:', error.message);
}
The API returned a server-side error. These are retried automatically. If all retry attempts fail, the final error is thrown.
if (error.type === 'server') {
  console.log('Server error, SDK will retry:', error.message);
}

​
Automatic retries

The SDK automatically retries retryable errors — network failures, 5xx responses, and rate limit hits (429) — using exponential backoff. You configure retry behavior when constructing the client: 
const client = new SWCombine({
  token: process.env.SWC_ACCESS_TOKEN!,
  maxRetries: 5,    // retry up to 5 times (default: 3)
  retryDelay: 500,  // base delay in ms, doubles each attempt (default: 1000)
});
For rate limit responses, the SDK also respects the Retry-After header returned by the API and waits the specified duration before retrying — regardless of the configured retryDelay.
When all retry attempts are exhausted, the SDK throws the final SWCError. Your catch block always receives the last error that occurred, not the first.

​
Error type quick reference

TypeHTTP statusRetryable
not_found404No
unauthorized401No
authvariesNo
validation400No
network—Yes
server5xxYes
Rate limit429Yes

​
Branching on error type

For applications that need to respond differently to different failures, branch on error.type rather than error.statusCode — the type values are stable across SDK versions: 
try {
  const faction = await client.faction.get({ uid: '4:1' });
} catch (error) {
  if (!(error instanceof SWCError)) throw error;

  switch (error.type) {
    case 'not_found':
      // Show a "faction not found" message to the user
      break;
    case 'unauthorized':
      // Redirect to re-authentication
      break;
    case 'network':
    case 'server':
      // These were already retried — show a service unavailable message
      break;
    default:
      // Log unexpected error types
      console.error('Unexpected error type:', error.type, error.message);
  }
}

​
Next steps

Rate limits

Monitor your quota and understand how the SDK handles rate limit responses.

Client modes

Configure maxRetries and retryDelay when constructing the client.

Authentication overview

Understand token expiry and which scopes are required for each endpoint.

Pagination

Use pageDelay to avoid rate limit errors during auto-pagination.