# Errors and retries

The TypeScript SDK's one error type, RequestError, and its codes; which calls it sends again, and how idempotency keys make a send safe to retry.

Every failed call rejects with a `RequestError`, which the SDK exports with
`isRequestError`. It takes one from any copy of the package, by its brand,
and no other library's error of that name:

| Field | What it is |
| --- | --- |
| `kind` | `http` (the API answered a failure), `network`, `timeout`, `parse` (an answer that could not be read), or `abort` (the call's `signal`). |
| `status` | The HTTP status; `0` when nothing answered. |
| `code` | The API's `error`, a snake_case code such as `domain_not_verified`; `null` when the answer names none. |
| `body` | The answer as it came, typed `unknown`: its JSON when it parsed (from the API, an [`ErrorOrValidation`](/docs/sdks/typescript/types/error-or-validation): a `validation_failed` one carries its `issues`), else its text, else `null`. Narrow it before reading it. |
| `retryable` | `true` when nobody answered: the network failed, the call timed out, or a gateway answered `502`, `503` or `504`. It says the API may answer in a moment, not that sending again is safe: a write without an idempotency key may have landed, so read the state back first. A `429` is not `retryable`, yet always temporary: wait its `Retry-After`, then send again. |
| `response` | The `Response`, when one came: an `http` or a `parse` failure. |
| `attempts` | How many times the call was sent. |

```ts
import { isRequestError } from '@openemail/sdk'

try {
  await openemail.domains.create({ domain: 'example.com' })
} catch (error) {
  if (!isRequestError(error) || error.code !== 'domain_claimed_elsewhere') throw error  // another account holds it
}
```

A domain's codes show why: `domains.create` answers `400 domain_not_verified`
until the domain's ownership record is published (the answer names it), `409
domain_claimed_elsewhere` when another account holds the domain, and `409
domain_unavailable` for every other conflict, worded alike on purpose so that no
one can learn which domains exist.

The SDK types no refusal's body, but reads the one a first `domains.create`
needs: `ownershipRecordOf(error)` gives the record to publish as a `DnsRecord`,
its shape checked first, and `null` for any other error.

```ts
import { ownershipRecordOf } from '@openemail/sdk'

try {
  await openemail.domains.create({ domain: 'example.com' })
} catch (error) {
  const record = ownershipRecordOf(error)  // null for any other error
  if (!record) throw error
  console.log(record.type, record.name, record.value)  // publish it, then create again
}
```

**Decide on the code, never on the status alone**: one status covers several
conditions. Each method's page lists the refusals its operation documents, by
status, with their codes, as [`domains.create`](/docs/sdks/typescript/domains/create)
does, and [Error codes](/docs/sdks/typescript/error-codes) lists every code
with its statuses and the methods that can answer it. The API's conventions are in the
[API reference's overview](/docs/api/overview).

A bad argument (an option the operation does not take, a missing path
parameter) rejects with a `TypeError` instead, and nothing is sent.

## Retries and idempotent sends

- **A read** (`GET`) is retried by the client's policy: on what nobody
  answered (the network, a timeout, `502` to `504`), and on `408` and `429`,
  with jittered backoff, and `Retry-After` honoured up to `maxRetryAfter`
  (3 s by default: a longer wait is the caller's).
- **A send that takes an idempotency key** (`x-delivery-id`:
  [`messages.send`](/docs/sdks/typescript/messages/send), `.sendDraft`,
  `.append`, `.compose`, [`threads.reply`](/docs/sdks/typescript/threads/reply),
  [`templates.send`](/docs/sdks/typescript/templates/send), the MTA doors)
  gets a fresh one when the call gives none (`deliveryId: 'sdk_<uuid>'`, the
  same for each of the call's retries), and is retried like a read: the API
  converges on one send. Pass your own key to make your own retries safe too.
  After a send that failed, `deliveryIdOf(error)` answers the key it went out
  with (yours, or the one the SDK made), so a later send with it converges
  too:

  ```ts
  import { deliveryIdOf } from '@openemail/sdk'

  try {
    await openemail.messages.send(mailboxId, email)
  } catch (error) {
    const deliveryId = deliveryIdOf(error)  // null for any other error
    if (deliveryId) await openemail.messages.send(mailboxId, email, { deliveryId })
  }
  ```
- [`identities.update`](/docs/sdks/typescript/identities/update) takes an
  `idempotencyKey` only for a control change (`suspended`, `receiveHold`); the
  API refuses one on any other (`400 idempotency_key_unsupported`), so the
  client never fills it: pass your own with a control change, and it is then
  yours to retry.
- [`identities.create`](/docs/sdks/typescript/identities/create) that names a
  webhook (`messageWebhook`, `eventWebhook`) requires an `Idempotency-Key`
  header, 1 to 128 characters, which the API's document does not list as a
  parameter: send it in the call's `headers`
  (`{ headers: { 'Idempotency-Key': key } }`). A retry with the same key and
  body answers the same identity; it is yours to make, as the client sends
  such a create once.
- **Any other write** is never sent twice blind: a `POST` whose answer was
  lost may have landed. It is sent once more only when the API refused it
  before doing anything, a `429` (a rate limit, always temporary), after the
  `Retry-After` it asks for, when that is within `maxRetryAfter`. A long hold
  (a paused sender's `429 sending_paused`) is the caller's to wait out. A
  `503 temporary_failure` is not sent again: the API says a write that got it
  may have been applied, so read the state back, or send it again with an
  idempotency key where the operation takes one.
- A call's own `retry` wins over all of this: `retry: false`, or a policy,
  which vouches that sending it twice is harmless. A client made with
  `retry: false` retries nothing a call's own `retry` does not ask for.

## The retry policy

`retry` is `false` for none, a number of retries, or a policy (the type
`RetryOptions`), an object of these, each optional:

| Field | Default | What it is |
| --- | --- | --- |
| `attempts` | `2` | Retries after the first send: three sends at most. |
| `delay` | 300 ms | The backoff's base: a random wait up to 300 ms, then up to 600, and so on. |
| `maxDelay` | 3 s | The backoff's ceiling. |
| `maxRetryAfter` | 3 s | The longest `Retry-After` honoured: an answer that asks for longer rejects at once. |
| `methods` | `GET`, `HEAD`, `OPTIONS` | Which methods the client's policy retries (a call's own policy retries its call whatever its method). |
| `statuses` | `408`, `429`, `502`, `503`, `504` | Which answers are retried, with what nobody answered. |

A [live channel's](/docs/sdks/typescript/live-events) `retry` is its
reconnects instead: a number in a row that may fail, or a policy's
`attempts`, `delay` and `maxDelay`, never the client's.
