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

# Errors and retries

> What the SDK does for you and what is up to you.

## Errors

Every API error arrives as a `DocondaError`:

```ts theme={null}
import { DocondaError } from "@doconda/sdk"

try {
  await doconda.documents.create({ format: "docx", prompt: "Memo for the team" })
} catch (e) {
  if (!(e instanceof DocondaError)) throw e
  console.log(e.status)    // 402
  console.log(e.code)      // "insufficient_balance": stable, use it to decide
  console.log(e.message)   // explanation in English, for your logs
  console.log(e.errors)    // on 422: which field is wrong and why
  console.log(e.requestId) // give it to us if you contact support
}
```

The ones you will see most:

| `code` | What to do |
| - | - |
| `input_invalid` | Fix the request: `e.errors` tells you which field. |
| `insufficient_balance` | Top up your balance in the dashboard (or turn on auto top-up). |
| `unauthorized` | The key does not exist or has been revoked. |
| `region_mismatch` | The key belongs to another region: don't change `baseUrl`, the SDK already picks the right one. |
| `not_found` | That document does not belong to this project. |

The full list is in [errors](/en/guides/errors).

A document that **fails during processing** is not an exception: `create` returns it with `status: "failed"` and
`doc.error`. There is no charge.

## Retries

The SDK only retries network failures, `429` and `5xx`, waiting a little longer each time (or as long as the API says).
Errors in your request (`4xx`) are not retried: repeating them would give the same result.

## Never the same document twice

Every creation carries an `Idempotency-Key`: if a retry arrives after the first attempt actually succeeded, the API
returns the same document instead of creating (and charging for) another one.

If your program can repeat the operation on its own (a job that retries, a user who clicks twice), pass your own
key, stable for that operation:

```ts theme={null}
await doconda.documents.create({ format: "docx", prompt: "…" }, { idempotencyKey: `welcome-letter-${userId}` })
```

The API remembers it for 24 hours.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.