# SDK errors

The error classes the SDK throws, their fields, and the codes it handles for you.

A refusal of an edit is not an error. The API answers it with `200`, and you read it on the answer: `refused` is a code (an empty string when the edit was made), with `detail`, `limit` and, for a role, `candidates`. On a result across sizes, a refusal is `outcome: "refused"`.

Everything else the API answers with an error status is thrown. For the API's side, see [Errors](https://withmestra.com/docs/api/errors/).

## MestraError

```ts
import {
  MestraError,
} from "@withmestra/sdk";

try {
  await size.save();
} catch (e) {
  if (e instanceof MestraError) {
    console.log(e.status, e.code, e.field, e.details);
  } else throw e;
}
```

A `MestraError` has:

- `message`: the API's own message.
- `status`: the HTTP status.
- `code`: the API's error code, when it sent one.
- `field`: the request field the error is about, when it sent one.
- `details`: the rest of the error body, such as `limit`, `max` or `latest`.

## Classes

These extend `MestraError`.

| Class                 | When                                                                                                             |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `SizeChangedError`    | `412` `scene_changed`: the size changed since you opened it, or changed before a lost session could be replayed. |
| `VersionChangedError` | `412` `version_changed`: the master has a newer version. It adds `latest`, `by` and `byName`.                    |
| `SessionGoneError`    | `404` `session_gone`. The SDK recovers from this itself, so you see it only if recovery finds the session gone.  |
| `ReplayDivergedError` | A lost session was reopened and an edit answered differently from the first time. Nothing was saved.             |
| `SizesBusyError`      | `409` `sizes_busy`: another call across sizes by the same user is still running.                                 |
| `OperationGoneError`  | `404` `operation_gone`: the operation is unknown, has ended, or is another user's.                               |
| `WaitTimeoutError`    | Waiting for an operation took longer than `timeoutMs`. It adds `operation`; the operation carries on.            |

`saveSizes` throws a `TypeError` if you pass a master session.

## Codes

Any other error is a plain `MestraError`. Read `status` and `code`.

| Status and code                                                                                | Meaning                                                                                                                          |
| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `401` `invalid_token`                                                                          | The key isn't valid.                                                                                                             |
| `403` `wrong_key`                                                                              | The key lacks Designs · Read or Write.                                                                                           |
| `400` `master_only`                                                                            | A master edit on a size, or across sizes.                                                                                        |
| `400` `if_match`                                                                               | `If-Match` isn't a version number.                                                                                               |
| `400` with a `field`                                                                           | A bad request. `field` names it: `name`, `edits`, `X-Mestra-Edit-Session`, `idempotencyKey`, `campaign`, `sizes` or `edit.name`. |
| `404` `not_editable`, `campaign_not_found`, `headless_off`                                     | The size, run or campaign can't be edited or isn't found.                                                                        |
| `409` `not_editable`, `library_off`, `api_off`                                                 | Editing isn't available for this size or organisation.                                                                           |
| `409` `idempotency_conflict`                                                                   | The key was used for a different save or edit.                                                                                   |
| `409` `review_moved`                                                                           | A review round arrived while you saved. Save again.                                                                              |
| `412` `scene_changed`, `version_changed`                                                       | Thrown as `SizeChangedError` and `VersionChangedError`.                                                                          |
| `422` `stand_in`, `lossy`, `cannot_draw`                                                       | A save can't keep the design. Nothing was saved.                                                                                 |
| `428` `if_match_required`                                                                      | A save sent no `If-Match`.                                                                                                       |
| `400` `picture_sum`, `picture_empty`, `picture_short`, `picture_size`, `image_too_large`       | The picture is not acceptable. `image_too_large` carries `limit`.                                                                |
| `411` `picture_length`, `413` `picture_too_big`, `415` `picture_type`, `422` `run_images_full` | More picture refusals. `picture_too_big` and `run_images_full` carry `max`.                                                      |
| `429`                                                                                          | Too many requests.                                                                                                               |
| `502` `render_failed`                                                                          | Mestra couldn't draw the design.                                                                                                 |
| `503` `editor_unavailable`, `editor_busy`                                                      | Try again shortly.                                                                                                               |

On one size of a call across sizes, a failure is data: `outcome` is `failed`, `busy` or `not_editable`, with `status` and `code` where they apply.
