Error Handling

Learn how to properly handle API errors and build robust applications.

Error Response Format

All error responses follow a consistent format:

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "Missing required parameter: 'messages'",
    "param": "messages",
    "request_id": "req_abc123"
  }
}

Field Descriptions

type	Error type
code	Specific error code
message	Human-readable error description
param	Related parameter (if applicable)
request_id	Request ID for debugging

Error Codes

400

Bad Request

Invalid or malformed request parameters

Common causes:

• Missing required parameters
• Invalid parameter type
• Malformed JSON

401

Unauthorized

Invalid, missing, or expired API key

Common causes:

• Incorrect API key
• Revoked API key
• No API key provided

429

Rate Limited

Too many requests

Common causes:

• Exceeded requests per minute
• Exceeded concurrency limit
• Exceeded token quota

500

Internal Server Error

Internal server error

Common causes:

• Server malfunction
• Upstream model error
• System maintenance

503

Service Unavailable

Service temporarily unavailable

Common causes:

• System maintenance
• High load
• Model unavailable

Error Handling Best Practices

JavaScript / TypeScript

import { SkyAIError, RateLimitError, AuthError } from "@skyaiapp/sdk";

try {
  const response = await sky.route({ ... });
} catch (error) {
  if (error instanceof RateLimitError) {
    // Handle rate limiting with exponential backoff
    const retryAfter = error.retryAfter || 60;
    console.log(`Rate limited. Retry after ${retryAfter}s`);
    await sleep(retryAfter * 1000);
    // Retry request
  } else if (error instanceof AuthError) {
    // Handle authentication errors
    console.error("Invalid API key");
    // Notify admin, refresh credentials, etc.
  } else if (error instanceof SkyAIError) {
    // Handle other API errors
    console.error(`API Error ${error.code}: ${error.message}`);
    console.error(`Request ID: ${error.requestId}`);
    // Log for debugging, show user-friendly message
  } else {
    // Handle unexpected errors
    console.error("Unexpected error:", error);
    throw error;
  }
}

Python

from skyaiapp.exceptions import (
    SkyAIError,
    RateLimitError,
    AuthenticationError,
    ValidationError
)
import time

try:
    response = sky.route(...)
except RateLimitError as e:
    # Handle rate limiting
    retry_after = e.retry_after or 60
    print(f"Rate limited. Retry after {retry_after}s")
    time.sleep(retry_after)
    # Retry request
except AuthenticationError:
    # Handle authentication errors
    print("Invalid API key")
    # Notify admin, refresh credentials, etc.
except ValidationError as e:
    # Handle validation errors
    print(f"Invalid request: {e.message}")
    print(f"Parameter: {e.param}")
except SkyAIError as e:
    # Handle other API errors
    print(f"API Error {e.code}: {e.message}")
    print(f"Request ID: {e.request_id}")
except Exception as e:
    # Handle unexpected errors
    print(f"Unexpected error: {e}")
    raise

Retry Strategy

For transient errors (like 429, 503), implement exponential backoff retry:

async function retryWithBackoff(fn, maxRetries = 3, baseDelay = 1000) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      const isRetryable = error instanceof RateLimitError || 
                          error.code === 503;
      
      if (!isRetryable || i === maxRetries - 1) {
        throw error;
      }

      // Exponential backoff with jitter
      const delay = baseDelay * Math.pow(2, i) * (1 + Math.random() * 0.1);
      await sleep(delay);
    }
  }
}

// Usage
const response = await retryWithBackoff(() =>
  sky.route({ goal: "cost", messages: [...] })
);

Best Practice

Add random jitter to avoid thundering herd, check X-RateLimit-Reset header before retry.

Debugging Errors

Each request has a unique request_id that can be used to view detailed logs and reproduce issues in the dashboard.

Debugging Steps

1.Capture and log request_id
2.Search for request_id in dashboard
3.View full request/response logs
4.Check timeline and model selection logic
5.Provide request_id when contacting support

Webhooks

Simple Routing

Was this page helpful?

Let us know how we can improve