# SearchError

Stable normalized failure codes with a trace and sanitized diagnostic fields.

Canonical: https://searchsdk.dev/docs/api/errors
Markdown: https://searchsdk.dev/docs/api/errors.md

<a id="handling"></a>

## Handle by code

> **TypeScript reference**
> The API names, code and policy behavior in this article describe the TypeScript SDK. See [your language guide](https://searchsdk.dev/docs/sdks) for its supported surface and limits.

**errors.ts · fixture**

```typescript
import { createSearch, SearchError } from '@belweave/search-sdk';
import { createMockProvider } from '@belweave/search-sdk/testing';

const client = createSearch({ provider: createMockProvider({
  outcomes: [{ type: 'error', code: 'rate_limit', retryAfterMs: 2_000 }],
}) });

try {
  await client.web.search({ query: 'SQLite concurrency' });
} catch (error) {
  if (!(error instanceof SearchError)) throw error;
  console.log(error.code, error.status, error.retryAfterMs);
  console.log(error.attempts); // Fixed codes and timing, no raw error bodies
}
```

<a id="codes"></a>

## Error codes

| Code | Fallback / meaning |
| --- | --- |
| `rate_limit` | Yes — HTTP 429. |
| `network` | Yes — rejected transport, including blocked redirects. |
| `unavailable` | Yes — HTTP 408 or 5xx. |
| `attempt_timeout` | Yes — attempt budget elapsed while total time remains. |
| `timeout` | No — total call budget elapsed. |
| `aborted` | No — caller cancelled. |
| `auth` | No — account/auth failures, including HTTP 401/402/403. |
| `invalid_request` | No — request or call options are invalid. |
| `unsupported_option` | No — a configured provider cannot satisfy a required option. |
| `configuration` | No — invalid setup or exhausted fixture outcomes. |
| `invalid_response` | No — malformed consumed response data. |
| `provider_error` | No — other rejected requests or custom exceptions. |

<a id="diagnostics"></a>

## Diagnostic fields

Read `code`, `attempts`, optional `status`, and optional `retryAfterMs`. Error messages are fixed by code. Raw provider bodies, transport messages, credentials, and caller abort reasons are excluded. Avoid attaching your own secret-bearing request objects to errors.