Errors - Hamlet API

Every non-2xx response uses a single, consistent envelope:

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found."
  }
}

code is a machine-readable value from the fixed set below — branch your logic on it.
message is a human-readable explanation. It may change over time; never parse or switch on it.

Error codes

The set of codes is closed and stable — new codes are added rarely and announced.

Code	HTTP	When
`invalid_request`	`400`	A malformed or invalid path, query, or body parameter (including a bad `cursor` or an offset-less `updated_since`).
`unauthorized`	`401`	Missing, malformed, invalid, or revoked API key.
`not_found`	`404`	Unknown resource, a resource outside your entitlements, or no such route.
`rate_limited`	`429`	Per-minute rate limit exhausted. Carries a `Retry-After` header.
`request_failed`	`4xx`/`5xx`	Catch-all for an otherwise-unclassified request failure.
`internal_error`	`500`	An unexpected server error. Retry later; if it persists, contact support.

Entitlement boundaries are enforced as 404, not 403: a resource your key isn’t entitled to is indistinguishable from one that doesn’t exist, so existence is never leaked across organizations.

Handling errors

Switch on error.code and treat the HTTP status as a coarse category:

resp = requests.get(url, headers=headers)
if resp.status_code == 429:
    wait = int(resp.headers.get("Retry-After", "1"))
    # back off for `wait` seconds, then retry
elif not resp.ok:
    code = resp.json()["error"]["code"]
    # branch on `code` — e.g. refresh credentials on "unauthorized"

​Error codes

​Handling errors

Error codes

Handling errors