> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raysurfer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for all publicly exposed SDK functions and types

This page documents all publicly exposed functions and types in the Raysurfer SDK. Every type is defined down to primitive fields.

***

## High-Level Client

### RaysurferClient

Drop-in replacement for Claude Agent SDK's `ClaudeSDKClient`.

<CodeGroup>
  ```python Python theme={null}
  from raysurfer import RaysurferClient
  from claude_agent_sdk import ClaudeAgentOptions

  options = ClaudeAgentOptions(
      allowed_tools=["Read", "Write", "Bash"],
      system_prompt="You are a helpful assistant.",
  )

  async with RaysurferClient(options) as client:
      await client.query("Your task here")
      async for msg in client.response():
          print(msg)
  ```

  ```typescript TypeScript theme={null}
  import { RaysurferClient } from "raysurfer";

  const client = new RaysurferClient({
    allowedTools: ["Read", "Write", "Bash"],
    systemPrompt: "You are a helpful assistant.",
  });

  for await (const msg of client.query("Your task here")) {
    console.log(msg);
  }
  ```
</CodeGroup>

#### Constructor Parameters

**Python** — `RaysurferClient(options, workspace_id=None, debug=False)`:

| Parameter      | Type                 | Description                                                 |
| -------------- | -------------------- | ----------------------------------------------------------- |
| `options`      | `ClaudeAgentOptions` | Standard Claude Agent SDK options                           |
| `workspace_id` | `string`             | Workspace ID for per-customer isolation (Pro or Enterprise) |
| `debug`        | `boolean`            | Enable debug logging                                        |

**TypeScript** — `new RaysurferClient(options)` where options is a single object:

| Parameter      | Type       | Description                                                 |
| -------------- | ---------- | ----------------------------------------------------------- |
| `allowedTools` | `string[]` | Allowed Claude tools                                        |
| `systemPrompt` | `string`   | System prompt                                               |
| `model`        | `string`   | Claude model ID                                             |
| `workspaceId`  | `string`   | Workspace ID for per-customer isolation (Pro or Enterprise) |
| `debug`        | `boolean`  | Enable debug logging                                        |

#### Methods

| Method          | Description                                              |
| --------------- | -------------------------------------------------------- |
| `query(prompt)` | Send a query with automatic cache retrieval              |
| `response()`    | Async generator yielding response messages (Python only) |

***

## Low-Level API Client

### RaySurfer / AsyncRaySurfer

<CodeGroup>
  ```python Python theme={null}
  from raysurfer import RaySurfer, AsyncRaySurfer

  # Sync client
  client = RaySurfer(api_key="your_api_key")

  # Async client
  async with AsyncRaySurfer(api_key="your_api_key") as client:
      result = await client.search(task="Fetch GitHub repos")
  ```

  ```typescript TypeScript theme={null}
  import { RaySurfer } from "raysurfer";

  const client = new RaySurfer({ apiKey: "your_api_key" });
  const result = await client.search({ task: "Fetch GitHub repos" });
  ```
</CodeGroup>

#### Constructor Options

| Option                               | Type                      | Description                                                   |
| ------------------------------------ | ------------------------- | ------------------------------------------------------------- |
| `api_key` / `apiKey`                 | `string`                  | Your Raysurfer API key                                        |
| `base_url` / `baseUrl`               | `string`                  | API base URL (optional)                                       |
| `timeout`                            | `number`                  | Request timeout in seconds/ms                                 |
| `organization_id` / `organizationId` | `string`                  | Organization ID for team/enterprise namespacing               |
| `workspace_id` / `workspaceId`       | `string`                  | Workspace ID for per-customer namespacing (Pro or Enterprise) |
| `snips_desired` / `snipsDesired`     | `"company"` \| `"client"` | Scope of private snippets                                     |
| `public_snips` / `publicSnips`       | `boolean`                 | Include community public snippets                             |

***

## search

Search for cached code snippets by task description.

<CodeGroup>
  ```python Python theme={null}
  result = client.search(
      task="Fetch GitHub trending repos",
      top_k=5,
      min_verdict_score=0.3,
      prefer_complete=True,
  )

  for match in result.matches:
      print(f"{match.code_block.name}: {match.score}")
      print(f"  File: {match.filename}")
      print(f"  Source: {match.code_block.source[:80]}...")
  ```

  ```typescript TypeScript theme={null}
  const result = await client.search({
    task: "Fetch GitHub trending repos",
    topK: 5,
    minVerdictScore: 0.3,
    preferComplete: true,
  });

  for (const match of result.matches) {
    console.log(`${match.codeBlock.name}: ${match.score}`);
    console.log(`  File: ${match.filename}`);
    console.log(`  Source: ${match.codeBlock.source.slice(0, 80)}...`);
  }
  ```
</CodeGroup>

### Parameters

| Parameter                                           | Type      | Default  | Description                                                                         |
| --------------------------------------------------- | --------- | -------- | ----------------------------------------------------------------------------------- |
| `task`                                              | `string`  | required | Natural language task description (any length)                                      |
| `top_k` / `topK`                                    | `number`  | `5`      | Maximum number of results                                                           |
| `min_verdict_score` / `minVerdictScore`             | `number`  | `0.3`    | Minimum quality score filter                                                        |
| `prefer_complete` / `preferComplete`                | `boolean` | `false`  | Prefer longer/more complete implementations                                         |
| `input_schema` / `inputSchema`                      | `object`  | `null`   | Optional input schema filter                                                        |
| `per_function_reputation` / `perFunctionReputation` | `boolean` | `false`  | Inject per-function diagnostics into matched source and return `functions` metadata |

### Returns: [SearchResponse](#searchresponse)

<Note>
  Queries can be any length, but shorter queries (under 200 characters) give the best accuracy and speed. Longer queries are automatically rephrased into multiple shorter searches and merged, which adds latency and may reduce precision.
</Note>

<Tip>
  **LLM prompt augmentation**: The legacy convenience method `get_code_files()` / `getCodeFiles()` wraps `search()` and returns an `add_to_llm_prompt` string. Use `search()` directly for full control over results.
</Tip>

***

## upload

Upload a code file from an execution for future reuse.

<CodeGroup>
  ```python Python theme={null}
  from raysurfer.types import FileWritten

  file = FileWritten(path="fetch_repos.py", content="def fetch(): ...")

  # Let Raysurfer AI vote (default behavior)
  result = client.upload(
      task="Fetch GitHub trending repos",
      file_written=file,
      succeeded=True,
      execution_logs="Fetched 10 trending repos successfully",
  )

  # Or provide your own vote (AI voting is automatically skipped)
  result = client.upload(
      task="Fetch GitHub trending repos",
      file_written=file,
      succeeded=True,
      user_vote=1,  # 1 = thumbs up, -1 = thumbs down
  )

  print(f"Stored {result.code_blocks_stored} code blocks")
  ```

  ```typescript TypeScript theme={null}
  const file = { path: "fetch_repos.ts", content: "function fetch() { ... }" };

  // Let Raysurfer AI vote (default behavior)
  const result = await client.upload({
    task: "Fetch GitHub trending repos",
    fileWritten: file,
    succeeded: true,
    executionLogs: "Fetched 10 trending repos successfully",
  });

  // Or provide your own vote (AI voting is automatically skipped)
  const result2 = await client.upload({
    task: "Fetch GitHub trending repos",
    fileWritten: file,
    succeeded: true,
    userVote: 1, // 1 = thumbs up, -1 = thumbs down
  });

  console.log(`Stored ${result.codeBlocksStored} code blocks`);
  ```
</CodeGroup>

### Parameters

| Parameter                                           | Type                                        | Default  | Description                                                                                                        |
| --------------------------------------------------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `task`                                              | `string`                                    | required | The task that was executed                                                                                         |
| `file_written` / `fileWritten`                      | [FileWritten](#filewritten)                 | required | The file created during execution                                                                                  |
| `succeeded`                                         | `boolean`                                   | required | Whether the task completed successfully                                                                            |
| `use_raysurfer_ai_voting` / `useRaysurferAiVoting`  | `boolean`                                   | `true`   | Let Raysurfer AI vote on stored blocks. Ignored when `user_vote` is provided.                                      |
| `user_vote` / `userVote`                            | `int \| null`                               | `null`   | User-provided vote: `1` for thumbs up, `-1` for thumbs down. When provided, AI voting is automatically skipped.    |
| `vote_source` / `voteSource`                        | `"ai" \| "human" \| null`                   | `null`   | Explicitly sets the vote source. When omitted, `user_vote` defaults to `"human"` and AI voting defaults to `"ai"`. |
| `vote_count` / `voteCount`                          | `int \| null`                               | `1`      | Number of votes to apply. Useful for pre-seeding community votes.                                                  |
| `execution_logs` / `executionLogs`                  | `string \| null`                            | `null`   | Captured stdout/stderr for vote context                                                                            |
| `dependencies`                                      | `dict[str, str]` / `Record<string, string>` | `null`   | Package dependencies with versions (e.g., `{"pandas": "2.1.0"}`)                                                   |
| `per_function_reputation` / `perFunctionReputation` | `boolean`                                   | `false`  | Extract function fingerprints and track per-function reputation for this upload                                    |

### Returns: [SubmitExecutionResultResponse](#submitexecutionresultresponse)

<Note>
  When `use_raysurfer_ai_voting` is `true` (the default) and no `user_vote` is provided, each newly stored code block is automatically evaluated by Raysurfer's AI. If you provide a `user_vote`, AI voting is skipped entirely — your vote is applied directly.
</Note>

***

## upload\_bulk\_code\_snips / uploadBulkCodeSnips

Bulk upload prompts, logs, and code files for sandboxed grading.

<CodeGroup>
  ```python Python theme={null}
  from raysurfer.types import FileWritten, LogFile

  files = [
      FileWritten(path="app.py", content="def main(): ..."),
      FileWritten(path="utils.py", content="def helper(): ..."),
  ]

  logs = [
      LogFile(path="logs/run.log", content="Task completed", encoding="utf-8"),
  ]

  # Let Raysurfer AI grade each file (default behavior)
  result = client.upload_bulk_code_snips(
      prompts=["Build a CLI tool", "Add CSV support"],
      files_written=files,
      log_files=logs,
  )

  # Or provide your own votes (AI grading is automatically skipped)
  result = client.upload_bulk_code_snips(
      prompts=["Build a CLI tool", "Add CSV support"],
      files_written=files,
      log_files=logs,
      user_votes={
          "app.py": 1,     # thumbs up
          "utils.py": -1,  # thumbs down
      },
  )
  ```

  ```typescript TypeScript theme={null}
  const files = [
    { path: "app.ts", content: "function main() { ... }" },
    { path: "utils.ts", content: "function helper() { ... }" },
  ];

  const logs = [
    { path: "logs/run.log", content: "Task completed", encoding: "utf-8" },
  ];

  // Let Raysurfer AI grade each file (default behavior)
  const result = await client.uploadBulkCodeSnips({
    prompts: ["Build a CLI tool", "Add CSV support"],
    filesWritten: files,
    logFiles: logs,
  });

  // Or provide your own votes (AI grading is automatically skipped)
  const result2 = await client.uploadBulkCodeSnips({
    prompts: ["Build a CLI tool", "Add CSV support"],
    filesWritten: files,
    logFiles: logs,
    userVotes: { "app.ts": 1, "utils.ts": -1 },
  });
  ```
</CodeGroup>

### Parameters

| Parameter                                           | Type                            | Default  | Description                                                                                                         |
| --------------------------------------------------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `prompts`                                           | `string[]`                      | required | Ordered list of raw user prompts                                                                                    |
| `files_written` / `filesWritten`                    | [FileWritten](#filewritten)`[]` | required | Code files to store and grade                                                                                       |
| `log_files` / `logFiles`                            | [LogFile](#logfile)`[]`         | `null`   | Log files (any format; use `encoding: "base64"` for binary)                                                         |
| `use_raysurfer_ai_voting` / `useRaysurferAiVoting`  | `boolean`                       | `true`   | Let Raysurfer AI grade and vote on stored blocks. Ignored when `user_votes` is provided.                            |
| `user_votes` / `userVotes`                          | `dict[str, int] \| null`        | `null`   | Dict of filename to vote (`1` = thumbs up, `-1` = thumbs down). When provided, AI grading is automatically skipped. |
| `vote_source` / `voteSource`                        | `"ai" \| "human" \| null`       | `null`   | Explicitly sets the vote source. When omitted, `user_votes` defaults to `"human"` and AI voting defaults to `"ai"`. |
| `vote_count` / `voteCount`                          | `int \| null`                   | `1`      | Number of votes to apply per file. Useful for pre-seeding community votes.                                          |
| `per_function_reputation` / `perFunctionReputation` | `boolean`                       | `false`  | Extract function fingerprints and track per-function reputation for each uploaded file                              |

### Returns: [BulkExecutionResultResponse](#bulkexecutionresultresponse)

***

## delete

Delete a snippet and all its associated data (vectors, retrieval logs, votes).

<CodeGroup>
  ```python Python theme={null}
  # Delete by ID
  result = client.delete(snippet_id="cb_abc123")

  # Or delete by name
  result = client.delete(snippet_id="weather_fetcher.py")

  print(f"Deleted {result.deleted_count} snippet(s)")
  ```

  ```typescript TypeScript theme={null}
  // Delete by ID
  const result = await client.delete("cb_abc123");

  // Or delete by name
  const result2 = await client.delete("weather_fetcher.py");

  console.log(`Deleted ${result.deletedCount} snippet(s)`);
  ```
</CodeGroup>

### Parameters

| Parameter                      | Type     | Default  | Description                             |
| ------------------------------ | -------- | -------- | --------------------------------------- |
| `snippet_id` / `snippetId`     | `string` | required | The ID or name of the snippet to delete |
| `workspace_id` / `workspaceId` | `string` | `null`   | Override client-level workspace ID      |

### Returns: [DeleteResponse](#deleteresponse)

***

## vote\_code\_snip / voteCodeSnip

Vote on whether a cached code snippet was useful. This triggers background voting on the backend.

<CodeGroup>
  ```python Python theme={null}
  client.vote_code_snip(
      task="Fetch GitHub trending repos",
      code_block_id="abc123",
      code_block_name="github_fetcher",
      code_block_description="Fetches trending repos",
      succeeded=True,
  )
  ```

  ```typescript TypeScript theme={null}
  await client.voteCodeSnip({
    task: "Fetch GitHub trending repos",
    codeBlockId: "abc123",
    codeBlockName: "github_fetcher",
    codeBlockDescription: "Fetches trending repos",
    succeeded: true,
  });
  ```
</CodeGroup>

### Returns: [VoteCodeSnipResponse](#votecodesnipresponse)

<Note>
  Voting is triggered automatically by `upload` when `use_raysurfer_ai_voting` is `true` (the default), and also by the high-level `RaysurferClient`. Use `vote_code_snip` directly only for voting on cached blocks after reuse.
</Note>

***

## Response Types

### SearchResponse

Returned by [`search()`](#search).

| Field                        | Type                            | Description                            |
| ---------------------------- | ------------------------------- | -------------------------------------- |
| `matches`                    | [SearchMatch](#searchmatch)`[]` | Matching code blocks with scoring      |
| `total_found` / `totalFound` | `int`                           | Total matches found                    |
| `cache_hit` / `cacheHit`     | `boolean`                       | Whether results were served from cache |

***

### SubmitExecutionResultResponse

Returned by [`upload()`](#upload).

| Field                                     | Type             | Description                         |
| ----------------------------------------- | ---------------- | ----------------------------------- |
| `success`                                 | `boolean`        | Whether the operation succeeded     |
| `code_blocks_stored` / `codeBlocksStored` | `int`            | Number of code blocks stored        |
| `message`                                 | `string`         | Human-readable status message       |
| `snippet_name` / `snippetName`            | `string \| null` | Name assigned to the stored snippet |

***

### BulkExecutionResultResponse

Returned by [`upload_bulk_code_snips()`](#upload_bulk_code_snips--uploadbulkcodesnips).

| Field                                     | Type             | Description                                 |
| ----------------------------------------- | ---------------- | ------------------------------------------- |
| `success`                                 | `boolean`        | Whether the operation succeeded             |
| `code_blocks_stored` / `codeBlocksStored` | `int`            | Number of code blocks stored                |
| `votes_queued` / `votesQueued`            | `int`            | Number of votes queued for AI grading       |
| `message`                                 | `string`         | Human-readable status message               |
| `status_url` / `statusUrl`                | `string \| null` | URL to check grading status (if applicable) |

***

### DeleteResponse

Returned by [`delete()`](#delete).

| Field                            | Type      | Description                     |
| -------------------------------- | --------- | ------------------------------- |
| `success`                        | `boolean` | Whether the operation succeeded |
| `deleted_count` / `deletedCount` | `int`     | Number of snippets deleted      |
| `message`                        | `string`  | Human-readable status message   |

***

### VoteCodeSnipResponse

Returned by [`vote_code_snip()`](#vote_code_snip--votecodesnip).

| Field                          | Type      | Description                                        |
| ------------------------------ | --------- | -------------------------------------------------- |
| `success`                      | `boolean` | Whether the operation succeeded                    |
| `vote_pending` / `votePending` | `boolean` | Whether the vote is being processed asynchronously |
| `message`                      | `string`  | Human-readable status message                      |

***

## Data Types

### SearchMatch

A single result from [`search()`](#search). Contains a full [CodeBlock](#codeblock) plus a relevance score.

| Field                        | Type                                                  | Description                                                          |
| ---------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------- |
| `code_block` / `codeBlock`   | [CodeBlock](#codeblock)                               | The matched code block with full source and metadata                 |
| `score`                      | `float`                                               | Overall relevance score (0–1)                                        |
| `thumbs_up` / `thumbsUp`     | `int`                                                 | Total positive votes on this code block                              |
| `thumbs_down` / `thumbsDown` | `int`                                                 | Total negative votes on this code block                              |
| `filename`                   | `string`                                              | Generated filename (e.g., `"github_fetcher.py"`)                     |
| `language`                   | `string`                                              | Programming language (e.g., `"python"`, `"typescript"`)              |
| `entrypoint`                 | `string`                                              | Main function name to call (e.g., `"fetch_repos"`)                   |
| `dependencies`               | `dict[str, str]` / `Record<string, string>`           | Package name to version (e.g., `{"httpx": "0.27.0"}`)                |
| `functions`                  | [FunctionReputation](#functionreputation)`[] \| null` | Per-function reputation and telemetry metadata (only when requested) |

***

### FunctionReputation

Per-function reputation metadata returned on `SearchMatch.functions`.

| Field                                        | Type             | Description                                 |
| -------------------------------------------- | ---------------- | ------------------------------------------- |
| `fingerprint`                                | `string`         | Stable function fingerprint                 |
| `function_name` / `functionName`             | `string`         | Function name                               |
| `signature`                                  | `string`         | Function signature text                     |
| `execution_count` / `executionCount`         | `int`            | Number of tracked executions                |
| `thumbs_up` / `thumbsUp`                     | `int`            | Positive votes attributed to this function  |
| `thumbs_down` / `thumbsDown`                 | `int`            | Negative votes attributed to this function  |
| `last_success_at` / `lastSuccessAt`          | `string \| null` | Last success timestamp (ISO 8601)           |
| `last_failure_at` / `lastFailureAt`          | `string \| null` | Last failure timestamp (ISO 8601)           |
| `common_errors` / `commonErrors`             | `string[]`       | Frequent error messages                     |
| `avg_output_size` / `avgOutputSize`          | `float`          | Average output size observed from telemetry |
| `output_completeness` / `outputCompleteness` | `float`          | Non-empty output ratio (0.0 to 1.0)         |
| `repeat_call_rate` / `repeatCallRate`        | `float`          | Repeat invocation ratio from telemetry      |
| `total_logged_calls` / `totalLoggedCalls`    | `int`            | Number of logged telemetry calls            |
| `author_agent` / `authorAgent`               | `string \| null` | Authoring agent identifier when available   |
| `reviewed_by_human` / `reviewedByHuman`      | `boolean`        | Whether this function received human review |
| `derived_from` / `derivedFrom`               | `string \| null` | Parent fingerprint lineage, if derived      |

***

### CodeBlock

A stored code block with full metadata. Nested inside [SearchMatch](#searchmatch).

| Field                                  | Type                                        | Description                                                      |
| -------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------- |
| `id`                                   | `string`                                    | Unique identifier (UUID)                                         |
| `name`                                 | `string`                                    | Human-readable name (e.g., `"GitHub Trending Fetcher"`)          |
| `description`                          | `string`                                    | What the code does                                               |
| `source`                               | `string`                                    | The full source code                                             |
| `entrypoint`                           | `string`                                    | Main function/method name                                        |
| `language`                             | `string`                                    | Programming language                                             |
| `language_version` / `languageVersion` | `string \| null`                            | Language version (e.g., `"3.12"`)                                |
| `dependencies`                         | `dict[str, str]` / `Record<string, string>` | Package name to version (e.g., `{"pandas": "2.1.0"}`)            |
| `tags`                                 | `string[]`                                  | Searchable tags (e.g., `["github", "api"]`)                      |
| `capabilities`                         | `string[]`                                  | What the code can do (e.g., `["http_requests", "json_parsing"]`) |
| `input_schema` / `inputSchema`         | `JsonDict` / `Record<string, JsonValue>`    | JSON schema describing expected inputs                           |
| `output_schema` / `outputSchema`       | `JsonDict` / `Record<string, JsonValue>`    | JSON schema describing outputs                                   |
| `example_queries` / `exampleQueries`   | `string[] \| null`                          | Example task queries this code is good for                       |
| `created_at` / `createdAt`             | `string \| null`                            | ISO 8601 timestamp of creation                                   |
| `updated_at` / `updatedAt`             | `string \| null`                            | ISO 8601 timestamp of last update                                |

***

## Input Types

### FileWritten

A file created during agent execution. Used by [`upload()`](#upload) and [`upload_bulk_code_snips()`](#upload_bulk_code_snips--uploadbulkcodesnips).

| Field     | Type     | Description                          |
| --------- | -------- | ------------------------------------ |
| `path`    | `string` | File path (e.g., `"fetch_repos.py"`) |
| `content` | `string` | Full file contents as a string       |

***

### LogFile

A log file for bulk grading. Used by [`upload_bulk_code_snips()`](#upload_bulk_code_snips--uploadbulkcodesnips).

| Field                          | Type                  | Default   | Description                                         |
| ------------------------------ | --------------------- | --------- | --------------------------------------------------- |
| `path`                         | `string`              | required  | File path (e.g., `"logs/run.log"`)                  |
| `content`                      | `string`              | required  | File contents (plain text or base64-encoded binary) |
| `encoding`                     | `"utf-8" \| "base64"` | `"utf-8"` | Content encoding. Use `"base64"` for binary files.  |
| `content_type` / `contentType` | `string \| null`      | `null`    | MIME type (e.g., `"application/json"`)              |

***

## Enums

### ExecutionState

Technical execution outcome.

| Value       | Description                     |
| ----------- | ------------------------------- |
| `COMPLETED` | Execution finished successfully |
| `ERRORED`   | Execution threw an error        |
| `TIMED_OUT` | Execution exceeded time limit   |
| `CANCELLED` | Execution was cancelled         |

### AgentVerdict

Agent's judgment on execution quality.

| Value         | Description              |
| ------------- | ------------------------ |
| `THUMBS_UP`   | Execution was useful     |
| `THUMBS_DOWN` | Execution was not useful |
| `PENDING`     | Not yet evaluated        |

### SnipsDesired

Scope of private snippets for retrieval.

| Value     | Required Tier     | Description                                         |
| --------- | ----------------- | --------------------------------------------------- |
| `company` | PRO or ENTERPRISE | Organization-level snippets                         |
| `client`  | PRO or ENTERPRISE | Client workspace snippets (requires `workspace_id`) |

***

## Exceptions

<Note>
  Both SDKs include built-in retry logic with exponential backoff for transient failures (429, 5xx, network errors). You don't need to implement your own retry logic for these cases.
</Note>

### RaySurferError

Base exception for all Raysurfer errors.

| Property  | Type     | Description   |
| --------- | -------- | ------------- |
| `message` | `string` | Error message |

### APIError

Raised when the API returns an error response. Extends [RaySurferError](#raysurfererror).

| Property                     | Type     | Description      |
| ---------------------------- | -------- | ---------------- |
| `message`                    | `string` | Error message    |
| `status_code` / `statusCode` | `int`    | HTTP status code |

### AuthenticationError

Raised when the API key is invalid or missing. Extends [RaySurferError](#raysurfererror).

| Property  | Type     | Description   |
| --------- | -------- | ------------- |
| `message` | `string` | Error message |

### CacheUnavailableError

Raised when the cache backend is unreachable or returns an unexpected error. Extends [RaySurferError](#raysurfererror).

| Property  | Type     | Description   |
| --------- | -------- | ------------- |
| `message` | `string` | Error message |

### RateLimitError

Raised when the API rate limit is exceeded. The SDK automatically retries with exponential backoff before raising this error. Extends [RaySurferError](#raysurfererror).

| Property                     | Type          | Description                     |
| ---------------------------- | ------------- | ------------------------------- |
| `message`                    | `string`      | Error message                   |
| `retry_after` / `retryAfter` | `int \| null` | Seconds until rate limit resets |

### ValidationError

Raised when request validation fails. Extends [RaySurferError](#raysurfererror).

| Property  | Type             | Description                      |
| --------- | ---------------- | -------------------------------- |
| `message` | `string`         | Error message                    |
| `field`   | `string \| null` | The field that failed validation |