Errors

SkytellsError class, all error IDs, error levels (SDK / API / network), and handling patterns.

All SDK errors are instances of SkytellsError. This page covers the error class, all error IDs, and handling patterns.

`SkytellsError`

errorIdstring

Machine-readable code — use for branching.

messagestring

Human-readable summary.

detailsstring | Record<string, unknown>

Extra context for logging.

httpStatusnumber

HTTP status code, or 0 for non-HTTP errors.

requestIdstring

Skytells request correlation ID (for support).

errorTypestring

API error.type (e.g. "server_error").

errorCodestring

API error.code (e.g. "service_error").

SkytellsError uses Object.setPrototypeOf so instanceof works reliably across module boundaries.

Basic Error Handling

catch

import { SkytellsError } from 'skytells';

try {
const result = await client.run('flux-pro', {
  input: { prompt: '...' },
});
} catch (e) {
if (e instanceof SkytellsError) {
  switch (e.errorId) {
    case 'RATE_LIMIT_EXCEEDED':
      // retry after delay
      break;
    case 'MODEL_NOT_FOUND':
      // invalid model slug
      break;
    default:
      throw e;
  }
}
throw e;
}

Error Levels

SDK-level errors (`httpStatus: 0`)

No HTTP response was received — these originate inside the SDK.

`errorId`	When
`SDK_ERROR`	Generic SDK guard (e.g. `orchestratorApiKey` not set)
`ABORTED`	`AbortSignal` fired during `wait()` or `run()` polling
`WAIT_TIMEOUT`	`wait()` exceeded `maxWait` milliseconds
`PREDICTION_FAILED`	`run()` received a `"failed"` terminal status
`INVALID_JSON`	Response body was not valid JSON when expected
`WEBHOOK_SIGNATURE_INVALID`	Inbound webhook HMAC-SHA256 mismatch

API-level errors (`httpStatus >= 400`)

The request completed but the server returned an error response.

For complete API error reference including HTTP status codes, descriptions, and resolution guides, see API Error Responses in the API documentation.

Common API-level error IDs you'll encounter:

`errorId`	HTTP	When
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	Key valid but lacks permission
`MODEL_NOT_FOUND`	404	Model slug does not exist
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INVALID_INPUT`	422	Input validation failed
`INSUFFICIENT_CREDITS`	402	Account out of credits
`CONTENT_POLICY_VIOLATION`	451	Content violates usage policy
`INFERENCE_ERROR`	500	Model inference failed server-side
`INTERNAL_ERROR`	500	Internal server error

See API Error Responses for the complete list.

Network-level errors (`httpStatus: 0`)

Transport failures before a response is received.

`errorId`	When
`NETWORK_ERROR`	`fetch()` threw, DNS failure, connection refused
`REQUEST_TIMEOUT`	Client-side `AbortController` timeout fired

Handling Common Errors

Rate limiting

Use the SDK's built-in retry (see Reliability) or handle manually.

Authentication

Check that your API key is set, starts with sk-, and hasn't been revoked.

Model not found

Use client.models.list() to find valid model slugs.

Insufficient credits

Redirect users to billing when INSUFFICIENT_CREDITS or PAYMENT_REQUIRED is thrown.

Handling Patterns

Rate limiting

// Manual retry
async function withRateLimit<T>(fn: () => Promise<T>): Promise<T> {
try {
  return await fn();
} catch (e) {
  if (
    e instanceof SkytellsError &&
    (e.errorId === 'RATE_LIMIT_EXCEEDED' ||
     e.errorId === 'INFERENCE_RATE_LIMITED')
  ) {
    await new Promise(r => setTimeout(r, 5000));
    return fn();
  }
  throw e;
}
}

// Or use built-in retry
const client = Skytells(apiKey, {
retry: { retries: 3, retryDelay: 1000, retryOn: [429] },
});

`requestId` — Support Correlation

When an API error includes a request ID, include it when contacting Skytells support:

catch (e) {
  if (e instanceof SkytellsError && e.requestId) {
    console.error(`Request ID for support: ${e.requestId}`);
  }
}

`details`, `errorType`, `errorCode`

// details — safe to log, not always user-facing
console.error(e.details);
// string: "Model 'xyz' not found on Skytells"
// or object: { category: "inference", context: "..." }

// errorType / errorCode — detailed API metadata
e.errorType; // "server_error", "invalid_request_error"
e.errorCode; // "service_error", "model_not_found"

Use errorId for branching logic. Use errorType/errorCode for detailed logging.

Unknown / Future Error IDs

The API may return error IDs not listed in ApiErrorId. Always handle the default case:

switch (e.errorId) {
  case 'RATE_LIMIT_EXCEEDED': /* ... */ break;
  case 'MODEL_NOT_FOUND': /* ... */ break;
  default:
    logger.error('skytells_error', {
      errorId: e.errorId,
      httpStatus: e.httpStatus,
      requestId: e.requestId,
    });
    throw e;
}

API Error Responses — Complete API error reference with HTTP codes and resolution guides
Prediction Errors — Prediction-level error codes and troubleshooting
Rate Limits — Rate limiting behavior and retry strategies
Reliability — Retries, timeouts, and automatic error recovery
Predictions — Error handling for prediction lifecycle
Chat API — Error handling for chat completions
Responses API — Error handling for stateful responses
Models — Error handling for model queries
Safety — Content policy and safety error handling
Webhooks — WEBHOOK_SIGNATURE_INVALID error details
Orchestrator — SDK_ERROR when orchestratorApiKey is missing
Reference: Error types — Full SkytellsError, ApiErrorId type definitions

How is this guide?

Basic Error Handling

Handling Patterns

On this page