Overview

The Shape of an Error#

Every error has the same shape, with the content type application/json:

{
  "type": "error",
  "data": {
    "code": "https://docs.synthevents.io/errors/range-in-future",
    "description": "range reaches into the future: expected to on or before now",
    "details": {
      "to": "2030-01-01T00:00:00Z"
    }
  }
}

• code names the error. Its slug, such as range-in-future, reads as a statement of the problem. To tell errors apart in your code, use the code, which stays the same.
• description says what is wrong and what is expected, in lowercase.
• details locates the problem. A value in it is given as the request gave it, and a field is named by its path from the root of the body, such as range.from. If there is nothing to locate, details is an empty object.

How a Request Is Checked#

SynthEvents reports one error at a time, the first it finds:

1. A request to generate events without a valid token is refused with 401, before its body is read.
2. A body that is too large is refused with 413.
3. A body that is not a JSON object of the expected shape, such as because of an unknown field or a value of the wrong type, is refused with 400.
4. A body that lacks a field is refused with 400 before any of its values is judged, in the order domain, scenario, range, range.from, range.to, eventCount, seed, and format.
5. A value that is not valid is refused with 422, in the same order.
6. If every slot for generating is taken, the request is refused with 503.
7. If the range and the number of events do not fit together, the request is refused with 422 once SynthEvents has tried to size the run.

For read-data-set, a body that lacks name or format is refused with 400 before either value is judged, and a name that SynthEvents does not offer with 422 before a format it does not know.

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

Errors of generate-events#

These errors come from POST /api/v1/generate-events:

Errors of read-data-set#

These errors come from QUERY /api/v1/read-data-set, whose body has exactly the fields name and format:

Errors of read-domains#

These errors come from QUERY /api/v1/read-domains, whose body has to be exactly {}:

Other Status Codes#

A request to a route that does not exist is answered with 404 Not Found, and one with a method that a route does not take with 405 Method Not Allowed. Both come with a body in plain text, without a code. For the routes and their methods, see API.