Skip to main content
Reference
Helix Cloud query failures use one JSON envelope:
  • error is a stable, lower-snake-case code. Branch on this field.
  • msg is 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 error when deciding whether and how to retry.
  • write_outcome_unknown adds "retryable": false. Cypher statement errors add a details object; see Cypher errors.
The table below lists codes produced by the Cloud gateway itself. Errors raised by the database engine behind it use the same envelope; see the query error reference for those codes.

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 403 forbidden to a database API key, not 404, or 400 invalid_request without an Authorization header. Check the URL.
  • 400 invalid_request also covers:
    • a missing or malformed Authorization header (missing or malformed authorization header), or a malformed or repeated X-Helix-Database-Id or X-Helix-Tenant-Id header, which currently reports the same message;
    • any Idempotency-Key header, which is not supported;
    • X-Helix-Await-Durable: false on a write; Helix Cloud writes always wait for durability.
  • 429 carries one of four codes. Branch on error:
    • rate_limited: the database’s request bucket is empty. Honor Retry-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.
    Resending a resource_limit or query_memory_limit_exceeded request 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:
The category in 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 decode error 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 HTTP 408 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 used error for diagnostic text and code for the machine-readable value, while others returned only error. For Cloud gateway responses, migrate from this shape:
to 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.