Errors

When a request fails, the API returns a non-2xx HTTP status and a JSON body. Most failures share a common shape; a few return a reduced shape. The Error envelope reference describes every variation. This page covers how to handle errors in a client.

The standard shape

1
{
2
  "statusCode": 401,
3
  "message": "Invalid or expired token",
4
  "error": "Unauthorized",
5
  "meta": {
6
    "requestId": "4a3b2c1d-5e6f-4890-9abc-def0fedcba98",
7
    "timestamp": "2026-05-15T10:30:45.000Z"
8
  }
9
}

Branch on the HTTP status code

Field availability is not uniform: error, code, and meta may be absent, and some errors omit statusCode from the body entirely. The one signal always available is the HTTP status code of the response itself. Branch on that first. Use code when it is present for a more precise decision, but never require it.

Handle message as a string or an array

message is always present, but its type varies. For a validation failure it is an array of individual messages:

1
{
2
  "statusCode": 400,
3
  "message": [
4
    "latitude must not be less than -90",
5
    "latitude must not be greater than 90"
6
  ],
7
  "error": "Bad Request",
8
  "meta": {
9
    "requestId": "5e6f7a8b-9c0d-4123-a4b5-c6d7e8f9a0b1",
10
    "timestamp": "2026-05-15T10:30:45.000Z"
11
  }
12
}

Normalise it in your client, for example by joining an array into a single string before display.

Handling by status

Support traceability

When the response includes meta.requestId, log it. Including it in a support request lets the team locate the exact request and its server-side context.