Error Handling

import {
  ModelRelay,
  APIError,
  TransportError,
  ConfigError,
  StreamTimeoutError,
  ErrorCodes,
} from "@modelrelay/sdk";

try {
  const response = await mr.responses.text(
    "claude-sonnet-4-20250514",
    "You are helpful.",
    "Hello!"
  );
} catch (error) {
  if (error instanceof APIError) {
    // Server returned an error response
    console.log("Status:", error.status);
    console.log("Code:", error.code);
    console.log("Message:", error.message);
    console.log("Request ID:", error.requestId);

    // Check specific error types
    if (error.isRateLimit()) {
      console.log("Rate limited, retry later");
    } else if (error.isUnauthorized()) {
      console.log("Invalid API key");
    } else if (error.isValidation()) {
      console.log("Validation errors:", error.fields);
    } else if (error.isNotFound()) {
      console.log("Resource not found");
    }
  } else if (error instanceof TransportError) {
    // Network or connection error
    console.log("Transport error:", error.message);
    console.log("Kind:", error.kind); // "timeout" | "request" | "response"
  } else if (error instanceof StreamTimeoutError) {
    // Streaming timeout
    console.log("Stream timeout:", error.streamKind); // "ttft" | "idle" | "total"
    console.log("Timeout:", error.timeoutMs, "ms");
  } else if (error instanceof ConfigError) {
    // SDK configuration error
    console.log("Config error:", error.message);
  }
}

import (
    "errors"
    "log"

    sdk "github.com/modelrelay/sdk-go"
)

response, err := client.Responses.Text(ctx, model, system, user)
if err != nil {
    var apiErr sdk.APIError
    if errors.As(err, &apiErr) {
        // Server returned an error response
        log.Printf("Status: %d", apiErr.Status)
        log.Printf("Code: %s", apiErr.Code)
        log.Printf("Message: %s", apiErr.Message)
        log.Printf("Request ID: %s", apiErr.RequestID)

        // Check specific error types
        switch apiErr.Code {
        case sdk.ErrCodeRateLimit:
            log.Println("Rate limited, retry later")
        case sdk.ErrCodeUnauthorized:
            log.Println("Invalid API key")
        case sdk.ErrCodeValidation, sdk.ErrCodeInvalidInput:
            log.Println("Validation errors:", apiErr.Fields)
        case sdk.ErrCodeNotFound:
            log.Println("Resource not found")
        case sdk.ErrCodePaymentRequired:
            log.Println("Customer quota exceeded")
        }
        return
    }

    var transportErr sdk.TransportError
    if errors.As(err, &transportErr) {
        log.Printf("Transport error: %s", transportErr.Message)
        return
    }

    var timeoutErr sdk.StreamTimeoutError
    if errors.As(err, &timeoutErr) {
        log.Printf("Stream %s timeout after %s", timeoutErr.Kind, timeoutErr.Timeout)
        return
    }

    var configErr sdk.ConfigError
    if errors.As(err, &configErr) {
        log.Printf("Config error: %s", configErr.Reason)
        return
    }

    log.Fatal(err)
}

use modelrelay::{Client, ResponseBuilder, Error};

let result = ResponseBuilder::new()
    .model("claude-sonnet-4-20250514")
    .system("You are helpful.")
    .user("Hello!")
    .send(&client.responses())
    .await;

match result {
    Ok(response) => println!("{}", response.text()),
    Err(Error::Api(e)) => {
        // Server returned an error response
        eprintln!("Status: {}", e.status);
        eprintln!("Code: {}", e.code);
        eprintln!("Message: {}", e.message);
        if let Some(req_id) = &e.request_id {
            eprintln!("Request ID: {}", req_id);
        }

        // Check specific error types
        match e.code.as_str() {
            "RATE_LIMIT" => eprintln!("Rate limited, retry later"),
            "UNAUTHORIZED" => eprintln!("Invalid API key"),
            "VALIDATION_ERROR" | "INVALID_INPUT" => {
                eprintln!("Validation errors: {:?}", e.fields);
            }
            "NOT_FOUND" => eprintln!("Resource not found"),
            "PAYMENT_REQUIRED" => eprintln!("Customer quota exceeded"),
            _ => {}
        }
    }
    Err(Error::Transport(e)) => {
        // Network or connection error
        eprintln!("Transport error: {}", e.message);
    }
    Err(Error::StreamTimeout(e)) => {
        // Streaming timeout
        eprintln!("Stream {:?} timeout after {:?}", e.kind, e.timeout);
    }
    Err(Error::Config(e)) => {
        // SDK configuration error
        eprintln!("Config error: {}", e.reason);
    }
    Err(e) => return Err(e.into()),
}

async function callWithRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  let lastError: Error | undefined;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error as Error;

      if (error instanceof APIError && error.isRateLimit()) {
        // Exponential backoff: 1s, 2s, 4s, 8s...
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`Rate limited, retrying in ${delay}ms...`);
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }

      // Don't retry other errors
      throw error;
    }
  }

  throw lastError;
}

// Usage
const response = await callWithRetry(() =>
  mr.responses.text(model, system, user)
);

func callWithRetry[T any](ctx context.Context, fn func() (T, error), maxRetries int) (T, error) {
    var zero T
    var lastErr error

    for attempt := 0; attempt <= maxRetries; attempt++ {
        result, err := fn()
        if err == nil {
            return result, nil
        }
        lastErr = err

        var apiErr sdk.APIError
        if errors.As(err, &apiErr) && apiErr.IsRateLimit() {
            // Exponential backoff: 1s, 2s, 4s, 8s...
            delay := time.Duration(1<<attempt) * time.Second
            log.Printf("Rate limited, retrying in %s...", delay)

            select {
            case <-ctx.Done():
                return zero, ctx.Err()
            case <-time.After(delay):
                continue
            }
        }

        // Don't retry other errors
        return zero, err
    }

    return zero, lastErr
}

// Usage
response, err := callWithRetry(ctx, func() (*sdk.Response, error) {
    return client.Responses.Text(ctx, model, system, user)
}, 3)

use std::time::Duration;
use tokio::time::sleep;
use modelrelay::{Client, ResponseBuilder, Error};

async fn call_with_retry<T, F, Fut>(
    mut f: F,
    max_retries: u32,
) -> Result<T, Error>
where
    F: FnMut() -> Fut,
    Fut: std::future::Future<Output = Result<T, Error>>,
{
    let mut last_error = None;

    for attempt in 0..=max_retries {
        match f().await {
            Ok(result) => return Ok(result),
            Err(Error::Api(ref e)) if e.code == "RATE_LIMIT" => {
                // Exponential backoff: 1s, 2s, 4s, 8s...
                let delay = Duration::from_secs(1 << attempt);
                eprintln!("Rate limited, retrying in {:?}...", delay);
                sleep(delay).await;
                last_error = Some(Error::Api(e.clone()));
            }
            Err(e) => return Err(e),
        }
    }

    Err(last_error.unwrap())
}

// Usage
let response = call_with_retry(
    || async {
        ResponseBuilder::new()
            .model(model)
            .system(system)
            .user(user)
            .send(&client.responses())
            .await
    },
    3,
).await?;

const mr = ModelRelay.fromSecretKey(apiKey, {
  retry: {
    maxRetries: 3,
    initialDelayMs: 1000,
    maxDelayMs: 30000,
    backoffMultiplier: 2,
  },
});

client, err := sdk.NewClientFromSecretKey(apiKey,
    sdk.WithRetryConfig(sdk.RetryConfig{
        MaxAttempts:        3,
        InitialDelay:       time.Second,
        MaxDelay:           30 * time.Second,
        BackoffMultiplier:  2.0,
    }),
)

use std::time::Duration;
use modelrelay::{Client, RetryConfig};

let client = Client::from_secret_key(api_key)?
    .retry_config(RetryConfig {
        max_attempts: 3,
        initial_delay: Duration::from_secs(1),
        max_delay: Duration::from_secs(30),
        backoff_multiplier: 2.0,
    })
    .build()?;

const mr = ModelRelay.fromSecretKey(apiKey, {
  connectTimeoutMs: 5000,  // 5s to establish connection
  requestTimeoutMs: 60000, // 60s for request completion
});

client, err := sdk.NewClientFromSecretKey(apiKey,
    sdk.WithConnectTimeout(5*time.Second),
    sdk.WithRequestTimeout(60*time.Second),
)

use std::time::Duration;
use modelrelay::Client;

let client = Client::from_secret_key(api_key)?
    .connect_timeout(Duration::from_secs(5))   // 5s to establish connection
    .request_timeout(Duration::from_secs(60))  // 60s for request completion
    .build()?;

const stream = await mr.responses.stream(req, {
  streamTimeouts: {
    ttftMs: 30000,   // 30s to first token
    idleMs: 15000,   // 15s max between tokens
    totalMs: 120000, // 2min total
  },
});

try {
  for await (const event of stream) {
    // Process events
  }
} catch (error) {
  if (error instanceof StreamTimeoutError) {
    switch (error.streamKind) {
      case "ttft":
        console.log("Model took too long to start responding");
        break;
      case "idle":
        console.log("Stream went silent");
        break;
      case "total":
        console.log("Response exceeded time limit");
        break;
    }
  }
}

stream, err := client.Responses.Stream(ctx, req,
    sdk.WithStreamTTFTTimeout(30*time.Second),
    sdk.WithStreamIdleTimeout(15*time.Second),
    sdk.WithStreamTotalTimeout(2*time.Minute),
)
if err != nil {
    log.Fatal(err)
}
defer stream.Close()

for {
    event, ok, err := stream.Next()
    if err != nil {
        var timeoutErr sdk.StreamTimeoutError
        if errors.As(err, &timeoutErr) {
            switch timeoutErr.Kind {
            case sdk.StreamTimeoutTTFT:
                log.Println("Model took too long to start responding")
            case sdk.StreamTimeoutIdle:
                log.Println("Stream went silent")
            case sdk.StreamTimeoutTotal:
                log.Println("Response exceeded time limit")
            }
        }
        break
    }
    if !ok {
        break
    }
    // Process event
}

use std::time::Duration;
use futures_util::StreamExt;
use modelrelay::{ResponseBuilder, Error, StreamTimeoutKind};

let mut stream = ResponseBuilder::new()
    .model("claude-sonnet-4-20250514")
    .system("You are helpful.")
    .user("Hello!")
    .stream_ttft_timeout(Duration::from_secs(30))   // 30s to first token
    .stream_idle_timeout(Duration::from_secs(15))   // 15s max between tokens
    .stream_total_timeout(Duration::from_secs(120)) // 2min total
    .stream(&client.responses())
    .await?;

while let Some(event) = stream.next().await {
    match event {
        Ok(e) => {
            // Process event
        }
        Err(Error::StreamTimeout(e)) => {
            match e.kind {
                StreamTimeoutKind::TTFT => {
                    eprintln!("Model took too long to start responding");
                }
                StreamTimeoutKind::Idle => {
                    eprintln!("Stream went silent");
                }
                StreamTimeoutKind::Total => {
                    eprintln!("Response exceeded time limit");
                }
            }
            break;
        }
        Err(e) => return Err(e.into()),
    }
}