# Errors and retries (/docs/sdks/errors-and-retries)
Networks drop requests and services get busy. The SDK retries the failures that are likely to pass on a second try, and raises a specific error for the ones that won't, so your code can handle each case.

## What's retried [#whats-retried]

| Failure | Retried |
| --- | --- |
| Timeouts | Yes |
| Connection errors | Yes |
| `408`, `409`, `429`, `500`, `502`, `503`, `504` | Yes |
| Any other status | No. The matching error is raised at once. |

The SDK waits 0.5 seconds before the first retry and doubles the wait each time, up to 8 seconds. It retries up to 3 times by default. Set `max_retries` (Python) or `maxRetries` (TypeScript) to change that, or `0` to turn retries off.

## Errors [#errors]

Every error extends `DockleeError`.

| Error | Raised when | Retried first |
| --- | --- | --- |
| `BadRequestError` | `400`: the request is malformed. | No |
| `AuthenticationError` | `401`: the key is missing, malformed, or revoked. | No |
| `PermissionDeniedError` | `403`: the key isn't allowed this request. | No |
| `NotFoundError` | `404`: the engine, space, or route doesn't exist. | No |
| `UnprocessableEntityError` | `422`: the request didn't pass validation. | No |
| `RateLimitError` | `429`: a rate limit was hit. | Yes |
| `InternalServerError` | `500` and above. | Yes, for `500`, `502`, `503`, and `504` |
| `APIStatusError` | Any other error status. Also the parent of every error above. | No |
| `APITimeoutError` | The request timed out on every attempt. | Yes |
| `APIConnectionError` | Docklee couldn't be reached on every attempt. Also the parent of `APITimeoutError`. | Yes |

## Error fields [#error-fields]

| Python | TypeScript | On | Description |
| --- | --- | --- | --- |
| `message` | `message` | Every error | What went wrong. |
| `status_code` | `statusCode` | `APIStatusError` and its subclasses | The HTTP status. |
| `response` | `response` | `APIStatusError` and its subclasses | The error body from the API. |
| `retry_after` | `retryAfter` | `RateLimitError` | Seconds to wait, from the `Retry-After` header, when it's sent. |

## Handle errors [#handle-errors]

<CodeTabs items={['Python', 'TypeScript']}>
  <Tab value="Python">
    ```python
    from docklee import (
        Lynk,
        APIConnectionError,
        AuthenticationError,
        PermissionDeniedError,
        RateLimitError,
    )

    lynk = Lynk()

    try:
        records = lynk.recall_sync("display preferences", end_user="user_8f2c")
    except AuthenticationError:
        raise SystemExit("Check DOCKLEE_API_KEY.")
    except PermissionDeniedError as error:
        print("Key can't read this space:", error.message)
    except RateLimitError as error:
        print("Rate limited. Retry after", error.retry_after, "seconds.")
    except APIConnectionError:
        print("Docklee is unreachable. Try again shortly.")
    ```
  </Tab>
  <Tab value="TypeScript">
    ```ts
    import {
      Lynk,
      APIConnectionError,
      AuthenticationError,
      PermissionDeniedError,
      RateLimitError,
    } from 'docklee';

    const lynk = new Lynk();

    try {
      const records = await lynk.recall('display preferences', { endUser: 'user_8f2c' });
    } catch (error) {
      if (error instanceof AuthenticationError) {
        throw new Error('Check DOCKLEE_API_KEY.');
      } else if (error instanceof PermissionDeniedError) {
        console.error("Key can't read this space:", error.message);
      } else if (error instanceof RateLimitError) {
        console.error('Rate limited. Retry after', error.retryAfter, 'seconds.');
      } else if (error instanceof APIConnectionError) {
        console.error('Docklee is unreachable. Try again shortly.');
      } else {
        throw error;
      }
    }
    ```
  </Tab>
</CodeTabs>

## Setup errors [#setup-errors]

Some problems are caught before any request is sent:

| Message | Cause |
| --- | --- |
| `API key is required` | No key was passed and `DOCKLEE_API_KEY` isn't set. |
| `engine_id is required` (Python), `engineId is required` (TypeScript) | `query` or `retrieve` was called with no engine ID. |
| `memory_space_id is required` (Python), `memorySpaceId is required` (TypeScript) | `recall` was called with no memory space ID. |
| `DOCKLEE_DIMENSION must be a positive integer` | The dimension variable isn't a positive whole number. |
| `Dock instance is closed` | `capture` was called after `close`. |

In Python these are `ValueError` or `RuntimeError`. In TypeScript they're `Error`.

## Writes that fail [#writes-that-fail]

`Dock` handles failed sends differently from reads. `flush_sync()` in Python and `flush()` in TypeScript don't raise. They keep the events in the buffer and return `None` or `null`, so a capture is never lost to a brief outage. See [Batching and flush](/docs/memory/essentials/batching-and-flush).

## Next steps [#next-steps]

Your code handles every failure. Start building with a full example.

<Cards>
  <Card title="Quickstart" href="/docs/docklee/quickstart" description="Write, recall, and query end to end." />
  <Card title="Configuration" href="/docs/sdks/configuration" description="Retries, timeouts, and the API address." />
  <Card title="Types" href="/docs/sdks/types" description="Every result and its fields." />
</Cards>
