---
title: "SDK Errors"
description: "The Aeontel SDK throws typed APIError subclasses you can catch and inspect."
section: "Libraries"
group: "SDK"
---

# SDK Errors

The SDK maps HTTP status codes to dedicated error classes. Every subclass extends `APIError`, which carries the `status` code and response `headers`.

| Status | Class                   | Notes                         |
| ------ | ----------------------- | ----------------------------- |
| 400    | `BadRequestError`       | Input or validation failure   |
| 401    | `AuthenticationError`   | Missing or invalid key        |
| 403    | `PermissionDeniedError` | Authenticated but not allowed |
| 404    | `NotFoundError`         | Resource doesn't exist        |
| 409    | `ConflictError`         | e.g. duplicate handle         |
| 429    | `RateLimitError`        | Rate-limited. Auto-retried.   |
| 5xx    | `InternalServerError`   | Auto-retried.                 |
| —      | `APIConnectionError`    | DNS / socket failure          |
| —      | `APITimeoutError`       | Exceeded `timeout` option     |

Each class is also attached as a static property on `Aeontel` for `instanceof` checks without extra imports.

## Example

```ts
import Aeontel from "@aeontel/sdk";

const client = new Aeontel("sec_...");

try {
  await client.agents.retrieve({ id: "agt_bogus" });
} catch (err) {
  if (err instanceof Aeontel.NotFoundError) {
    console.warn("Agent not found");
  } else if (err instanceof Aeontel.AuthenticationError) {
    console.error("Bad API key", err.headers.get("x-request-id"));
  } else if (err instanceof Aeontel.APITimeoutError) {
    console.warn(`Timed out after ${err.timeout}ms`);
  } else {
    throw err;
  }
}
```

## Retries

429 and 5xx responses are automatically retried with exponential backoff. The number of retries is controlled by the `maxRetries` option (default: 2) passed to the client constructor. Client-side errors (400/401/403/404/409) are thrown immediately.