Errors

Every refusal, its status and its code

Every refusal has the same shape, RFC 9457 problem details, and a stable code your software can branch on.

The shape

404

{
  "type": "https://developers.hatcel.com/errors#not_found",
  "title": "Nothing was found there",
  "status": 404,
  "code": "not_found",
  "request_id": "req_8c1f2e4b6a9d0c3e5f7a1b2c"
}

Branch on code, never on title or detail - the sentences may be reworded, the codes will not. Nothing internal is ever in a refusal: no database message, no stack.

Codes

Code	Status	Sent when
`invalid_request`	400	A parameter, a cursor or a body field is not valid, or a POST has no `Idempotency-Key`. `detail` names it.
`unsupported_version`	400	The `Hatcel-Version` header names a version other than 2026-10-08.
`unauthorized`	401	No key, a malformed key, or a key that is revoked, expired or unknown - all one answer.
`forbidden`	403	The key cannot do this: a read only key writing, a live key asking a test only endpoint, or `marketing_consent` set to `true`.
`key_paused`	403	The key was paused automatically for unusual activity. Nothing will work until it is resumed: the `detail` says how.
`not_found`	404	No such endpoint, or no record with that id that this key can see.
`method_not_allowed`	405	The endpoint exists but does not take that method.
`conflict`	409	The write clashes with what is there: an email already on another customer, an email or phone already set being changed, or the same Idempotency-Key still in flight.
`payload_too_large`	413	The body is over 64 KB.
`unsupported_media_type`	415	A body was sent without `Content-Type: application/json`.
`idempotency_mismatch`	422	That Idempotency-Key was already used with a different request.
`precondition_failed`	412	The `If-Match` version is not the record's current one: it changed since you read it. GET it again and decide afresh.
`precondition_required`	428	The change needed `If-Match` and had none. Send the `ETag` from your last read.
`rate_limited`	429	A limit was reached: the key's, its workspace's or its writes'. Wait the `Retry-After` seconds.
`internal_error`	500	Something failed on our side. Retry, and quote the `request_id` if it persists.

Request ids

Every answer, success or refusal, carries a Request-Id header, and a refusal repeats it as request_id. Quote it to support and we can find the request.

What to retry

rate_limited: wait the Retry-After seconds, then retry.
internal_error: retry with backoff. Retry a POST with the same Idempotency-Key, so it can never write twice.
key_paused: stop. A person has to resume the key before anything works.
Everything else: fix the request. Sending it again will get the same answer.

Prompts Rate limits