Timeouts

Soxom supports configurable request timeouts at global, per-operation, and runtime levels.

Timeout Types

Type	Description	Default
default_ms	Total request timeout	60000ms (1 min)
connect_ms	Connection establishment	10000ms (10 sec)
read_ms	Time to first byte	30000ms (30 sec)

Configuration

Global Settings

timeouts:
  # Total request timeout (milliseconds)
  default_ms: 60000     # 60 seconds

  # Connection timeout
  connect_ms: 10000     # 10 seconds

  # Read timeout (time to first byte)
  read_ms: 30000        # 30 seconds

  # Per-operation overrides
  operations:
    batch_process:
      default_ms: 300000    # 5 minutes
    reports_generate:
      default_ms: 120000    # 2 minutes
    upload_file:
      default_ms: 600000    # 10 minutes

Timeout Behavior

┌─────────────────────────────────────────────────────────────────┐
│                        Total Timeout (default_ms)                │
├────────────────┬────────────────────────────────────────────────┤
│   Connect      │              Read + Transfer                    │
│  (connect_ms)  │                                                 │
├────────────────┼─────────────────┬──────────────────────────────┤
│   TCP/TLS      │  First Byte     │     Response Body            │
│  Handshake     │   (read_ms)     │                              │
└────────────────┴─────────────────┴──────────────────────────────┘

• Connect timeout: Time allowed to establish TCP/TLS connection
• Read timeout: Time to receive first byte after sending request
• Total timeout: Overall limit for entire request lifecycle

Per-Operation Configuration

Use x-soxom-timeout in your OpenAPI spec:

paths:
  /reports/generate:
    post:
      x-soxom-timeout: 120000   # 2 minutes
      summary: Generate a report
      responses:
        "202":
          description: Report generation started

  /batch/import:
    post:
      x-soxom-timeout: 300000   # 5 minutes
      summary: Import batch data

  /files/upload:
    post:
      x-soxom-timeout: 600000   # 10 minutes
      summary: Upload a file

Tip

Use longer timeouts for operations that may take time: batch processing, file uploads, report generation.

Runtime Override

Override timeout per-request:

TypeScript

// Override timeout for a single request
const report = await client.reports.generate(params, {
  timeout: 120000  // 2 minutes
});

// Very long operation
const result = await client.batch.process(data, {
  timeout: 600000  // 10 minutes
});

Python

# Override timeout for a single request
report = client.reports.generate(
    params,
    timeout=120000  # 2 minutes
)

# Very long operation
result = client.batch.process(
    data,
    timeout=600000  # 10 minutes
)

Go

// Use context with timeout
ctx, cancel := context.WithTimeout(ctx, 2*time.Minute)
defer cancel()

report, err := client.Reports.Generate(ctx, params)

Client-Level Configuration

Set default timeout when creating the client:

TypeScript

const client = new Client({
  token: process.env.API_TOKEN,
  timeout: 30000,  // 30 seconds default
});

Python

client = Client(
    token=os.environ["API_TOKEN"],
    timeout=30000,  # 30 seconds default
)

Go

client := mysdk.NewClient(
    mysdk.WithToken(os.Getenv("API_TOKEN")),
    mysdk.WithTimeout(30 * time.Second),
)

Configuration Hierarchy

Timeout settings follow this precedence (highest to lowest):

1. Runtime - Per-request timeout option
2. Client - Client configuration
3. Per-operation - x-soxom-timeout in OpenAPI
4. Global - timeouts in soxom.yaml
5. Defaults - Soxom built-in defaults

Common Patterns

Fast Endpoints

For simple CRUD operations:

timeouts:
  default_ms: 30000     # 30 seconds
  connect_ms: 5000      # 5 seconds
  read_ms: 10000        # 10 seconds

Long-Running Operations

For batch processing, exports, etc.:

timeouts:
  default_ms: 60000

  operations:
    batch_process:
      default_ms: 300000
    export_data:
      default_ms: 600000

File Uploads

For large file transfers:

timeouts:
  operations:
    upload_file:
      default_ms: 1800000   # 30 minutes
      connect_ms: 10000
      read_ms: 60000

Error Handling

Timeout errors are specific error types:

TypeScript

import { TimeoutError } from 'my-sdk';

try {
  await client.reports.generate(params);
} catch (error) {
  if (error instanceof TimeoutError) {
    console.log("Request timed out");
    // Retry with longer timeout
    await client.reports.generate(params, {
      timeout: 300000
    });
  }
}

Python

from my_sdk import TimeoutError

try:
    client.reports.generate(params)
except TimeoutError:
    print("Request timed out")
    # Retry with longer timeout
    client.reports.generate(params, timeout=300000)

Best Practices

1. Set reasonable defaults - Most API calls should complete in under 30 seconds
2. Increase for specific operations - Batch, upload, export operations need more time
3. Use per-operation config for predictable slow endpoints
4. Handle timeout errors gracefully in your application

Next Steps

• Streaming - Server-Sent Events support
• Retries - Automatic retry configuration