# Overview

When EventSourcingDB refuses what a request asks for, it says so in the response, with status `200` and an item of the type `error`. Every error has a **code**, a URL of the form `https://docs.eventsourcingdb.io/errors/<slug>`, which leads to the page of that error in this documentation. This page explains how errors look and arrive, and lists them all.

## The Shape of an Error

Every error is an envelope of the type `error`:

```json
{
  "type": "error",
  "data": {
    "code": "https://docs.eventsourcingdb.io/errors/subject-malformed",
    "description": "subject is malformed: expected a slash-separated path such as '/books/42'",
    "details": {
      "value": "books/42"
    }
  }
}
```

- **`code`** names the error. Its slug, such as `subject-malformed`, reads as a statement of the problem. The code stays the same, so **use it to tell errors apart in your code**. The **[OpenAPI definition](/docs/eventsourcingdb/api/openapi)** of the v2 API lists, for every route, the codes it can report.
- **`description`** says what is wrong and what is expected. Where the database refuses a single event or precondition of a write for what it finds while carrying the write out, such as an event that does not match its schema or a precondition that does not hold, the description starts with its place in the request, as in `/events/3: …`. Where a value of an event or a precondition is missing or malformed, only `details` names its place.
- **`details`** locates the problem, for example the event or the precondition it concerns, by its place in its list, counting from 0, the bound, or the part of a backup, and repeats the value that caused it as **`value`**. Each error's page lists its details. If there is nothing to locate, `details` is an empty object.

## How an Error Arrives

Most routes answer with a **[stream](/docs/eventsourcingdb/api#streams)**, and there an error is an item like any other. In a stream that comes to an end, such as reading events, the error is followed by the `end` item, and nothing else follows. **Observing events** has no `end` item, so the response simply ends after the error. Routes that answer with a single envelope, such as reading a single event type, answer with the error itself.

An error can come **at the start** of a stream, before anything else, or **in its course**, after items have been sent, for example when the server begins to shut down. A stream that carries an error has not done what was asked for, even if it ends with `end`.

## How a Request Is Checked

EventSourcingDB reports **one error per request**, the first it finds:

1. A route that does not exist, a client that sent too many requests, a missing or invalid token, and a server that shuts down are answered with a **status code** rather than an error, see **[Errors](/docs/eventsourcingdb/api#errors)**.
2. A body that cannot be read, that is too large, or that does not have the shape the route expects is answered with **`400`**, **`408`**, or **`413`**.
3. The **values** of the request are checked next, one after the other, and the first that is missing or wrong is reported as an error.
4. Then the database does what the request asks for, and reports what stands in the way, such as a precondition that does not hold or read-only mode.

Two checks come earlier than this order suggests: an **expired license** is reported before any value of a write or a restore, as **[`license-invalid`](/docs/eventsourcingdb/errors/license-invalid)**, and a restore or an import checks the **state of the database**, such as whether it holds events, before it reads the backup or the events. An import checks the **shape of each line** before its values, as a body is checked, but reports it as **[`import-malformed`](/docs/eventsourcingdb/errors/import-malformed)** in the stream, since the stream has begun by then.

So if a request has several problems, fix the one EventSourcingDB reports and send it again.

## Events and Subjects

- **[`subject-missing`](/docs/eventsourcingdb/errors/subject-missing)**: The request leaves out a **subject**.
- **[`subject-malformed`](/docs/eventsourcingdb/errors/subject-malformed)**: A **subject** in the request is **not a valid subject**.
- **[`subject-too-long`](/docs/eventsourcingdb/errors/subject-too-long)**: A **subject** in the request, or of an event of a backup, is **longer than 1,024 characters**.
- **[`subject-too-deep`](/docs/eventsourcingdb/errors/subject-too-deep)**: A **subject** in the request, or of an event of a backup, has **more than 32 segments**.
- **[`source-missing`](/docs/eventsourcingdb/errors/source-missing)**: An event leaves out its **source**.
- **[`source-malformed`](/docs/eventsourcingdb/errors/source-malformed)**: The **source** of an event is **not a URI** as RFC 3986 defines it.
- **[`event-type-missing`](/docs/eventsourcingdb/errors/event-type-missing)**: The request leaves out an **event type**.
- **[`event-type-malformed`](/docs/eventsourcingdb/errors/event-type-malformed)**: An **event type** in the request is **not a valid event type**.
- **[`event-type-unknown`](/docs/eventsourcingdb/errors/event-type-unknown)**: The **event type** that the request asks for has **neither events nor a schema**.
- **[`data-missing`](/docs/eventsourcingdb/errors/data-missing)**: An event leaves out its **data**.
- **[`data-malformed`](/docs/eventsourcingdb/errors/data-malformed)**: The data of an event holds a **number beyond the range of a 64-bit floating-point number** or with **more than 1000 digits**.
- **[`event-too-large`](/docs/eventsourcingdb/errors/event-too-large)**: An event is **larger than the maximum event size** of 64 KiB.
- **[`traceparent-malformed`](/docs/eventsourcingdb/errors/traceparent-malformed)**: The **`traceparent`** of an event is **not valid** under W3C Trace Context.
- **[`tracestate-malformed`](/docs/eventsourcingdb/errors/tracestate-malformed)**: The **`tracestate`** of an event is **not valid** under W3C Trace Context.
- **[`tracestate-without-traceparent`](/docs/eventsourcingdb/errors/tracestate-without-traceparent)**: An event has a **`tracestate` without a `traceparent`**.
- **[`events-missing`](/docs/eventsourcingdb/errors/events-missing)**: A write holds **no events**.
- **[`event-id-missing`](/docs/eventsourcingdb/errors/event-id-missing)**: The request leaves out an **event ID**, such as that of a bound or an anchor.
- **[`event-id-malformed`](/docs/eventsourcingdb/errors/event-id-malformed)**: An **event ID** in the request is **not a non-negative integer written without a sign or a leading zero**.

## Reading and Observing

- **[`order-unknown`](/docs/eventsourcingdb/errors/order-unknown)**: The **order** of a read is neither `chronological` nor `antichronological`.
- **[`bound-type-missing`](/docs/eventsourcingdb/errors/bound-type-missing)**: A **bound** leaves out its **type**.
- **[`bound-type-unknown`](/docs/eventsourcingdb/errors/bound-type-unknown)**: The **type of a bound** is neither `inclusive` nor `exclusive`.
- **[`range-unsatisfiable`](/docs/eventsourcingdb/errors/range-unsatisfiable)**: The **bounds** of a read or an observation **leave no event** that could match.
- **[`from-latest-event-incomplete`](/docs/eventsourcingdb/errors/from-latest-event-incomplete)**: **`fromLatestEvent`** leaves out its subject, its type, or `ifEventIsMissing`.
- **[`if-event-is-missing-unknown`](/docs/eventsourcingdb/errors/if-event-is-missing-unknown)**: **`ifEventIsMissing`** has a **value that the route does not accept**.
- **[`selection-conflicting`](/docs/eventsourcingdb/errors/selection-conflicting)**: The **options** of a read or an observation **cannot be combined**.

## Preconditions and EventQL

- **[`precondition-type-missing`](/docs/eventsourcingdb/errors/precondition-type-missing)**: A **precondition** leaves out its **type**.
- **[`precondition-unknown`](/docs/eventsourcingdb/errors/precondition-unknown)**: A **precondition** has a **type that does not exist**.
- **[`payload-missing`](/docs/eventsourcingdb/errors/payload-missing)**: A **precondition** leaves out its **payload**.
- **[`precondition-violated`](/docs/eventsourcingdb/errors/precondition-violated)**: A **precondition** of a write **does not hold**, so **none of its events were written**.
- **[`query-missing`](/docs/eventsourcingdb/errors/query-missing)**: The request leaves out its **EventQL query**.
- **[`query-malformed`](/docs/eventsourcingdb/errors/query-malformed)**: An **EventQL query** does **not parse**.
- **[`query-too-deep`](/docs/eventsourcingdb/errors/query-too-deep)**: An **EventQL query** **nests more than 256 levels**, or holds a **chain of more than 10,000 operands**.
- **[`query-too-long`](/docs/eventsourcingdb/errors/query-too-long)**: The query of an **`isEventQlQueryTrue` precondition** is **longer than 100 KiB**.
- **[`query-unevaluable`](/docs/eventsourcingdb/errors/query-unevaluable)**: An **EventQL query** parses, but **fails while it runs**.
- **[`query-not-boolean`](/docs/eventsourcingdb/errors/query-not-boolean)**: The query of an **`isEventQlQueryTrue` precondition** does **not return exactly one boolean**.

## Event Schemas

- **[`event-schema-missing`](/docs/eventsourcingdb/errors/event-schema-missing)**: The request leaves out the **schema** to register.
- **[`event-schema-malformed`](/docs/eventsourcingdb/errors/event-schema-malformed)**: A **schema** is **not a valid JSON Schema**, for example because it refers to another document.
- **[`event-schema-not-object`](/docs/eventsourcingdb/errors/event-schema-not-object)**: A **schema** does **not describe an object** at its top level.
- **[`event-schema-too-complex`](/docs/eventsourcingdb/errors/event-schema-too-complex)**: A **schema** is **too complex** to validate against: it **refers back to a part of itself**, or reaches **more than 10,000 subschemas**.
- **[`event-schema-already-registered`](/docs/eventsourcingdb/errors/event-schema-already-registered)**: The event type **has a schema already**, which can be neither replaced nor removed.
- **[`event-schema-violated`](/docs/eventsourcingdb/errors/event-schema-violated)**: An event does **not match the schema** of its event type.
- **[`event-schema-unregistered`](/docs/eventsourcingdb/errors/event-schema-unregistered)**: An event has a type **without a schema**, while the database **requires schemas**.

## License

- **[`license-invalid`](/docs/eventsourcingdb/errors/license-invalid)**: The **license** of the database is **not valid**, so events can no longer be written.
- **[`capacity-exceeded`](/docs/eventsourcingdb/errors/capacity-exceeded)**: The events would **exceed the event capacity** of the license.

## State of the Database

- **[`store-read-only`](/docs/eventsourcingdb/errors/store-read-only)**: The database is in **read-only mode** and refuses every write.
- **[`read-only-mode-already-enabled`](/docs/eventsourcingdb/errors/read-only-mode-already-enabled)**: **Read-only mode** is **on already**, so enabling it changes nothing.
- **[`disk-full`](/docs/eventsourcingdb/errors/disk-full)**: The **disk is almost full**, so the database refuses writes until there is room again.
- **[`restore-in-progress`](/docs/eventsourcingdb/errors/restore-in-progress)**: A **restore is running**, which refuses reads and writes until it has finished.
- **[`store-failed`](/docs/eventsourcingdb/errors/store-failed)**: The database **has failed** and refuses writes, or reads and writes, **until it is restarted**.
- **[`indexes-rebuilding`](/docs/eventsourcingdb/errors/indexes-rebuilding)**: The database is **rebuilding its indexes** after an upgrade, which this request needs complete.
- **[`server-shutting-down`](/docs/eventsourcingdb/errors/server-shutting-down)**: The server **shuts down**, so the request ended before it was through.

## Auditing and Verifying

- **[`last-audited-event-missing`](/docs/eventsourcingdb/errors/last-audited-event-missing)**: The request leaves out **`lastAuditedEvent`**, which is `null` for a first audit.
- **[`last-audited-event-mismatched`](/docs/eventsourcingdb/errors/last-audited-event-mismatched)**: The event that **`lastAuditedEvent`** names has **another hash** in the database.
- **[`last-audited-event-unknown`](/docs/eventsourcingdb/errors/last-audited-event-unknown)**: The database holds **no event** with the ID that **`lastAuditedEvent`** names.
- **[`event-hash-missing`](/docs/eventsourcingdb/errors/event-hash-missing)**: An anchor names an event **without its hash**.
- **[`event-hash-malformed`](/docs/eventsourcingdb/errors/event-hash-malformed)**: The **hash** of an anchor is **not a valid hash**.
- **[`event-chain-broken`](/docs/eventsourcingdb/errors/event-chain-broken)**: An event **does not follow on the one before it**, so the chain of hashes is **broken**.
- **[`file-unreadable`](/docs/eventsourcingdb/errors/file-unreadable)**: Verifying the store **cannot read a file**, so the store was **not verified**.

## Backups

- **[`last-backed-up-event-missing`](/docs/eventsourcingdb/errors/last-backed-up-event-missing)**: The request leaves out **`lastBackedUpEvent`**, which is `null` for a full backup.
- **[`last-backed-up-event-mismatched`](/docs/eventsourcingdb/errors/last-backed-up-event-mismatched)**: The event that **`lastBackedUpEvent`** names has **another hash** in the database.
- **[`last-backed-up-event-unknown`](/docs/eventsourcingdb/errors/last-backed-up-event-unknown)**: The database holds **no event** with the ID that **`lastBackedUpEvent`** names.
- **[`store-not-empty`](/docs/eventsourcingdb/errors/store-not-empty)**: A restore needs an **empty database**, and an import one **without events**, but this one holds what it does not take.
- **[`full-backup-missing`](/docs/eventsourcingdb/errors/full-backup-missing)**: A restore **starts with an increment** rather than with a full backup.
- **[`backup-increment-disconnected`](/docs/eventsourcingdb/errors/backup-increment-disconnected)**: An increment **does not follow on the part before it**.
- **[`backup-format-unknown`](/docs/eventsourcingdb/errors/backup-format-unknown)**: A part of the backup has a **format version** that this version does not know.
- **[`event-hash-version-unknown`](/docs/eventsourcingdb/errors/event-hash-version-unknown)**: An event has a **hash of a version** that this version does not know.
- **[`backup-ahead-of-clock`](/docs/eventsourcingdb/errors/backup-ahead-of-clock)**: An event of the backup lies **more than an hour beyond the clock** of the server.
- **[`backup-malformed`](/docs/eventsourcingdb/errors/backup-malformed)**: A line of the backup is **not an item that a backup holds** there.
- **[`backup-incomplete`](/docs/eventsourcingdb/errors/backup-incomplete)**: A part of the backup **ends without its `end` item**, so it was cut.
- **[`backup-failed`](/docs/eventsourcingdb/errors/backup-failed)**: A part of the backup **holds an error**, so creating it had failed.
- **[`backup-unreadable`](/docs/eventsourcingdb/errors/backup-unreadable)**: Reading the backup **broke off**, for example because the client dropped the connection.

## Imports

An import reports **[`store-not-empty`](/docs/eventsourcingdb/errors/store-not-empty)** and **[`event-chain-broken`](/docs/eventsourcingdb/errors/event-chain-broken)** as well, and every error of an event of a restore, besides these:

- **[`import-malformed`](/docs/eventsourcingdb/errors/import-malformed)**: A line of the import is **not an event that an import takes**.
- **[`import-unreadable`](/docs/eventsourcingdb/errors/import-unreadable)**: Reading the events to import **broke off**, for example because the client dropped the connection.
- **[`import-ahead-of-clock`](/docs/eventsourcingdb/errors/import-ahead-of-clock)**: An event of the import lies **more than an hour beyond the clock** of the server.