Reference
Helix Cloud query failures use one JSON envelope:
erroris a stable, lower-snake-case code. Branch on this field.msgis a human-readable diagnostic. Log it, but do not parse it or depend on its exact text.- The HTTP status remains part of the contract. Use it with
errorwhen deciding whether and how to retry. write_outcome_unknownadds"retryable": false. Cypher statement errors add adetailsobject; see Cypher errors.
Gateway error reference
The text in
msg can include request-specific details. The error values and
HTTP statuses above are the compatibility surface.
Database engine failures pass through with the engine’s code and its
class status,
for example HTTP 409 unique_constraint_violation with "retryable": false when
another node already owns a unique value. The gateway reports a failed write as
write_outcome_unknown only when the engine cannot prove it committed nothing.
Other responses
-
Unknown paths return
403forbiddento a database API key, not404, or400invalid_requestwithout anAuthorizationheader. Check the URL. -
400invalid_requestalso covers:- a missing or malformed
Authorizationheader (missing or malformed authorization header), or a malformed or repeatedX-Helix-Database-IdorX-Helix-Tenant-Idheader, which currently reports the same message; - any
Idempotency-Keyheader, which is not supported; X-Helix-Await-Durable: falseon a write; Helix Cloud writes always wait for durability.
- a missing or malformed
-
429carries one of four codes. Branch onerror:rate_limited: the database’s request bucket is empty. HonorRetry-After.index_backpressure: a vector or text index holds too much unpublished work. Retry with bounded backoff ("retryable": true). See the query error reference.resource_limit: a Cypher statement exceeded a per-query budget; see Cypher errors.query_memory_limit_exceeded: a query exceeded its memory budget; reduce the data it retains.
resource_limitorquery_memory_limit_exceededrequest unchanged fails again.
Cypher errors
POST /v2/cypher, POST /v2/cypher/explain, POST /v2/sql and
POST /v2/sql/explain use the same envelope and gateway codes. A failed statement also carries a details object:
error and the condition in details.detail are lower snake case
codes, listed in the query error reference.
A resource_limit (HTTP 429) is a per-query budget, not the database’s request
rate: resending the same statement fails again, so reduce the work instead of
honoring Retry-After. Check error to tell it apart from rate_limited.
SDK access
Official SDKs decodeerror and msg into separate stable-code and diagnostic
fields. Non-JSON responses from older endpoints and intermediaries remain
available as readable diagnostics. Rust and TypeScript also retain the raw
response body separately.
The current SDK error objects do not expose response headers, including
Retry-After. Use direct HTTP or an application transport that retains headers
when the exact Cloud rate-limit delay is required.
Branch on the stable code while retaining the diagnostic:
Timed-out writes
An HTTP408 cancels the gateway’s wait, but a write can race with durable
commit. A write that the gateway already sent to the writer returns 503 with
write_outcome_unknown and "retryable": false instead. In both cases, treat the
outcome as unknown. Before resubmitting, reconcile using an identity stored in your data, such as
a unique ID property written with the record; the gateway rejects an Idempotency-Key header
with 400.
Migration from the previous shape
Some earlier responses usederror for diagnostic text and code for the
machine-readable value, while others returned only error. For Cloud gateway
responses, migrate from this shape:
error as the lower-snake-case code and msg as diagnostic text. Earlier
gateways also reported unknown write outcomes and unavailable failover waits in
that shape, as {"code":"WRITE_OUTCOME_UNKNOWN","error":"<message>","retryable":false}
and "code":"FAILOVER_WAIT_UNAVAILABLE". They are now write_outcome_unknown and
failover_wait_unavailable in the envelope above, and Cypher categories and
details, formerly upper camel case such as ResourceLimit, are lower snake case.
Current SDKs read both shapes. Keep a readable diagnostic fallback for
intermediaries and older self-hosted endpoints that do not return the Cloud
envelope.