Error Handling

The SDK provides typed error classes for different failure scenarios.

Error types

Error class	When thrown	HTTP status
`LaunchGateError`	Base class for all SDK errors	—
`AuthError`	Invalid or missing API key	401
`PaymentError`	Monthly run limit exceeded	402
`ValidationError`	Invalid request parameters	400
`NetworkError`	Network connectivity issues	—

Error properties

All error types extend LaunchGateError:


class LaunchGateError extends Error {
  code: string;      // Machine-readable error code
  message: string;   // Human-readable message
  hint?: string;     // Suggested fix (when available)
}

ValidationError includes additional detail:


class ValidationError extends LaunchGateError {
  details?: object;  // Field-level validation errors
}

Handling errors


import {
  LaunchGate,
  AuthError,
  PaymentError,
  ValidationError,
  NetworkError,
} from "@launchgate/sdk";
 
const lg = new LaunchGate({ apiKey: process.env.LAUNCHGATE_API_KEY! });
 
try {
  const result = await lg.run("my-suite", { output: "..." });
} catch (error) {
  if (error instanceof AuthError) {
    // Invalid or revoked API key
    console.error("Auth failed:", error.message);
  } else if (error instanceof PaymentError) {
    // Monthly run limit exceeded — upgrade plan
    console.error("Limit reached:", error.message);
  } else if (error instanceof ValidationError) {
    // Bad request — check your parameters
    console.error("Validation:", error.message, error.details);
  } else if (error instanceof NetworkError) {
    // Network issue — the SDK already retried 3 times
    console.error("Network error:", error.message);
  }
}

In most cases, you won’t need to catch errors explicitly. The SDK’s graceful degradation returns status: "skipped" when the API is unreachable, so your application continues running. Errors are only thrown for issues that require your attention (auth, payment, validation).

Retry behaviour

The SDK retries automatically for transient errors:

Error type	Retried?	Reason
Network errors	Yes (3x)	Transient connectivity issues
5xx server errors	Yes (3x)	Server-side transient failures
429 rate limit	Yes (3x)	Temporary rate limiting
401 auth errors	No	Invalid credentials won’t self-resolve
402 payment errors	No	Requires plan upgrade
400 validation errors	No	Request must be fixed

After 3 failed retries on retriable errors, the SDK returns a "skipped" result rather than throwing.