Error Types

SDK-Level Error Handling: SkytellsError is the SDK-specific error class that wraps both API errors (from Error Responses) and SDK-level errors (network issues, timeouts, validation). ApiErrorId enum combines API error codes with SDK-specific codes for unified error handling.

See Errors for handling patterns.

SkytellsError

class SkytellsError extends Error {
  errorId: string;
  details: string | Record<string, unknown>;
  httpStatus: number;
  requestId?: string;
  errorType?: string;
  errorCode?: string;
}

Field	Type	Description
`errorId`	`string`	Machine-readable code — use for branching.
`message`	`string`	Human-readable summary.
`details`	`string \| Record<string, unknown>`	Extra context for logging.
`httpStatus`	`number`	HTTP status code, or `0` for non-HTTP errors.
`requestId`	`string`	Skytells request correlation ID (for support).
`errorType`	`string`	API `error.type` (e.g. `"server_error"`).
`errorCode`	`string`	API `error.code` (e.g. `"service_error"`).

ApiErrorId

Unified error ID enum combining SDK-specific errors with API error codes.

SDK-Specific Errors (httpStatus: 0)

These errors originate in the SDK, not from the API:

enum ApiErrorId {
  SDK_ERROR                = 'SDK_ERROR',                // Generic SDK error
  ABORTED                  = 'ABORTED',                  // Request aborted via AbortSignal
  WAIT_TIMEOUT             = 'WAIT_TIMEOUT',             // Polling maxWait exceeded
  PREDICTION_FAILED        = 'PREDICTION_FAILED',        // Prediction reached 'failed' status
  INVALID_JSON             = 'INVALID_JSON',             // JSON parse error
  WEBHOOK_SIGNATURE_INVALID= 'WEBHOOK_SIGNATURE_INVALID',// HMAC verification failed
  NETWORK_ERROR            = 'NETWORK_ERROR',            // Network connectivity issue
  REQUEST_TIMEOUT          = 'REQUEST_TIMEOUT',          // HTTP request timeout
}

API Error Codes (httpStatus >= 400)

These codes correspond to API Error Responses. The SDK normalizes API error.code values into this enum:

enum ApiErrorId {
  // Authentication & Authorization
  UNAUTHORIZED             = 'UNAUTHORIZED',           // 401
  FORBIDDEN                = 'FORBIDDEN',              // 403
  ACCOUNT_SUSPENDED        = 'ACCOUNT_SUSPENDED',      // 403
  SECURITY_VIOLATION       = 'SECURITY_VIOLATION',     // 403
  
  // Resource Errors
  MODEL_NOT_FOUND          = 'MODEL_NOT_FOUND',        // 404
  ENDPOINT_NOT_FOUND       = 'ENDPOINT_NOT_FOUND',     // 404
  
  // Rate Limiting
  RATE_LIMIT_EXCEEDED      = 'RATE_LIMIT_EXCEEDED',    // 429
  RATE_LIMITED             = 'RATE_LIMITED',           // 429
  INFERENCE_RATE_LIMITED   = 'INFERENCE_RATE_LIMITED', // 429
  
  // Validation Errors
  INVALID_INPUT            = 'INVALID_INPUT',          // 422
  INVALID_PARAMETER        = 'INVALID_PARAMETER',      // 422
  INVALID_DATE_FORMAT      = 'INVALID_DATE_FORMAT',    // 422
  INVALID_DATE_RANGE       = 'INVALID_DATE_RANGE',     // 422
  INVALID_REQUEST          = 'INVALID_REQUEST',        // 400
  
  // Billing
  INSUFFICIENT_CREDITS     = 'INSUFFICIENT_CREDITS',   // 402
  PAYMENT_REQUIRED         = 'PAYMENT_REQUIRED',       // 402
  
  // Content Policy
  CONTENT_POLICY_VIOLATION = 'CONTENT_POLICY_VIOLATION',// 451
  
  // Server Errors
  INFERENCE_ERROR          = 'INFERENCE_ERROR',        // 500
  INFERENCE_TIMEOUT        = 'INFERENCE_TIMEOUT',      // 504
  INTERNAL_ERROR           = 'INTERNAL_ERROR',         // 500
  SERVICE_UNAVAILABLE      = 'SERVICE_UNAVAILABLE',    // 503
  
  // Generic
  API_ERROR                = 'API_ERROR',              // varies
  HTTP_ERROR               = 'HTTP_ERROR',             // varies
  SERVER_ERROR             = 'SERVER_ERROR',           // varies
  UNKNOWN_ERROR            = 'UNKNOWN_ERROR',          // varies
}

See API Error Reference for detailed error descriptions and resolution steps. See SDK Error Handling for usage patterns.

Error Handling Patterns

import { SkytellsError, ApiErrorId } from 'skytells';

try {
  await client.run('flux-pro', { prompt: '...' });
} catch (err) {
  if (err instanceof SkytellsError) {
    switch (err.errorId) {
      case ApiErrorId.UNAUTHORIZED:
        console.error('Invalid API key');
        break;
      case ApiErrorId.RATE_LIMIT_EXCEEDED:
        console.error('Rate limited, retry after delay');
        break;
      case ApiErrorId.INSUFFICIENT_CREDITS:
        console.error('Out of credits');
        break;
      case ApiErrorId.NETWORK_ERROR:
        console.error('Network issue, retry');
        break;
      default:
        console.error(`Error: ${err.errorId} - ${err.message}`);
    }
  }
}

See Error Handling for comprehensive patterns.

SDK Error Handling — Complete error handling guide with patterns and examples
API Error Reference — Full API error codes and resolution steps
SDK Reliability — Retry configuration and timeout handling

How is this guide?

SkytellsError

ApiErrorId

SDK-Specific Errors (httpStatus: 0)

API Error Codes (httpStatus >= 400)

Error Handling Patterns

Related

On this page