Errors

When a request fails, HAPI v3 returns a real HTTP status code and a single, predictable error object. There is never a 200 hiding a failure.

The error object

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "slices is required.",
    "param": "slices",
    "doc_url": "https://api.hermeseus.com/docs/errors#validation_failed",
    "request_id": "req_z8iukwo8qwf488s01gthblxb"
  }
}

Field	Description
`type`	A broad category you can branch on (see below).
`code`	A specific machine-readable code for the exact problem.
`message`	A human-readable explanation. Do not match on this string.
`param`	Present when one field caused the error; names that field.
`doc_url`	A link to the relevant documentation.
`request_id`	The id of this request; quote it to support.

Error types

Type	HTTP	Meaning
`authentication_error`	401	The token is missing, invalid, or expired.
`permission_error`	403	The token lacks a required scope.
`invalid_request_error`	400 / 422	The request was malformed or failed validation.
`not_found_error`	404	No resource matched.
`conflict_error`	409	The request conflicts with current state.
`insufficient_balance`	402	The office wallet cannot cover the booking.
`rate_limit_error`	429	You are sending requests too quickly.
`api_error`	5xx	Something failed on our side.

Common codes

Code	Type	Fix
`missing_authorization`	authentication	Add the `Authorization: Bearer` header.
`invalid_token`	authentication	The token is unknown; request a new one.
`expired_token`	authentication	Get a fresh token and retry.
`invalid_client`	authentication	Check the client id and secret.
`insufficient_scope`	permission	Use a token that holds the scope named in `detail`.
`validation_failed`	invalid_request	Fix the field named in `param`; `detail` lists all issues.
`not_found`	not_found	Check the id in the path.
`insufficient_balance`	insufficient_balance	Top up the office wallet, then retry.
`rate_limited`	rate_limit	Back off and retry after a short delay.
`internal_error`	api	Retry; if it persists, contact support with the `request_id`.

Handling errors

Branch on type for behaviour and on code for the exact case. Retry 429 and 5xx with exponential backoff; do not blindly retry 4xx other than 429, since the request itself needs to change. Always log the request_id.

Validation detail. A 422 validation_failed carries a detail object mapping each rejected field to its problems, so you can surface every error at once instead of one at a time.

Was this page helpful?

Conventions

Environments