Error Codes

Conventional HTTP status codes are returned to indicate the success or failure of an API request. Certain errors are retryable, meaning that re-issuing the same request after a delay could lead to a successful result. Exponential backoff is recommended.

In the context of an S2S append or read session, an error that occurs after a 200 OK status will be a “terminal message” on the response stream. However, pre-flight errors are sent normally.

Standard Errors

A standard error body has the following JSON form:

{
  "code": "brief_reason",
  "message": "more information about the error"
}

Code	HTTP Status	Retryable	Side Effect
`bad_header`	400	No	No
`bad_path`	400	No	No
`bad_query`	400	No	No
`bad_json`	400	No	No
`bad_proto`	400	No	No
`bad_frame`	400	No	No
`invalid`	422	No	No
`permission_denied`	403	No	No
`quota_exhausted`	403	No	No
`basin_not_found`	404	No	No
`stream_not_found`	404	No	No
`access_token_not_found`	404	No	No
`request_timeout`	408	Yes	Maybe
`resource_already_exists`	409	No	No
`basin_deletion_pending`	409	No	No
`stream_deletion_pending`	409	No	No
`transaction_conflict`	409	Yes	No
`rate_limited`	429	Yes	No
`other`	500	Yes	Maybe
`storage`	500	Yes	Maybe
`hot_server`	502	Yes	No
`unavailable`	503	Yes	No
`upstream_timeout`	504	Yes	Maybe

Requests that fail with 404 or 409 will succeed on a future attempt once the underlying condition changes (e.g., resource is created, or deletion completes).

Structured Errors

Append Condition Failed (412)

See append concurrency control for more context.

Fencing Token Mismatch
Sequence Number Mismatch

{
  "fencing_token_mismatch": "the-actual-fencing-token"
}

The current fencing token did not match the expected fencing token, which is returned.

{
  "seq_num_mismatch": 42
}

The expected sequence number did not match the assignable sequence number, which is returned.

Starting Point Out of Range (416)

416 without a Range header? Unconventional, but the shoe fits.See the precise conditions under which this is returned in response to a read request.

{
  "tail": {
    "seq_num": 42,
    "timestamp": 1767996832000
  }
}

The tail field indicates the current end position of the stream.

records

access tokens

streams

basins

metrics

Error Codes

Standard Errors

Structured Errors

Append Condition Failed (412)

Starting Point Out of Range (416)

records

access tokens

streams

basins

metrics

​Standard Errors

​Structured Errors

​Append Condition Failed (412)

​Starting Point Out of Range (416)

Standard Errors

Structured Errors

Append Condition Failed (412)

Starting Point Out of Range (416)