Modeling
SynthEvents
Remembering
EventSourcingDB
Building
ArchitectureKit
Version
1.3 · latest1.21.11.0
Docs / EventSourcingDB / Errors / Overview

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:

{
  "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 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, 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.
  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, 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 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#

Reading and Observing#

Preconditions and EventQL#

Event Schemas#

License#

  • license-invalid: The license of the database is not valid, so events can no longer be written.
  • capacity-exceeded: The events would exceed the event capacity of the license.

State of the Database#

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

Auditing and Verifying#

Backups#

Imports#

An import reports store-not-empty and event-chain-broken as well, and every error of an event of a restore, besides these:

  • import-malformed: A line of the import is not an event that an import takes.
  • import-unreadable: Reading the events to import broke off, for example because the client dropped the connection.
  • import-ahead-of-clock: An event of the import lies more than an hour beyond the clock of the server.