Runtime error codes

Failures on the ox runtime serve /v1 HTTP surface (Serving surface) carry a stable error.code string in the ARGON_RUNTIME_* family. This is the published failure reference an integrator switches on. Every 4xx/5xx response — including routing, method, and request-body parse failures — uses the same envelope, so a client can key on error.code uniformly:

{
  "error": { "code": "ARGON_RUNTIME_VALIDATION_FAILED", "message": "…", "details": { … } },
  "requestId": "…",
  "moduleHash": "…"
}

These are runtime codes — distinct from the compile-time OE#### catalog of Appendix C, which are build-time diagnostics. Runtime codes are an API contract surfaced at request time.

The set below is checked against the runtime’s canonical registry (RUNTIME_ERROR_CODES in oxc-serve): a drift test in oxc-serve fails if a code is emitted without a row here, or a row names a code the runtime does not emit. Do not hand-add a row without the matching registry entry.

Code	HTTP	Meaning
`ARGON_RUNTIME_VALIDATION_FAILED`	400	Argument coercion, entity-reference validation, or a malformed / wrong-content-type request body failed.
`ARGON_RUNTIME_SIGNATURE_MISMATCH`	400	Descriptor arguments do not match the declared `pub` callable’s parameters.
`ARGON_RUNTIME_MISSING_CONTEXT`	400	A required context field (e.g. `tenantId`) was absent from headers and body.
`ARGON_RUNTIME_FORK_CONFLICT`	400	The `x-fork-id` header and the request/path fork disagree.
`ARGON_RUNTIME_INVALID_CURSOR`	400	A pagination cursor was not issued by this server — pass back `nextCursor` verbatim or omit it.
`ARGON_RUNTIME_UNSUPPORTED_QUERY_BODY`	400	The declared query’s body uses a construct the served evaluator does not yet support.
`ARGON_RUNTIME_UNSUPPORTED_QUERY_RESULT`	400	The query’s result shape cannot be rendered on the wire.
`ARGON_RUNTIME_UNSUPPORTED_MUTATION_RESULT`	400	The mutation’s result shape cannot be rendered on the wire.
`ARGON_RUNTIME_DERIVE_FAILED`	400	A derive / projection evaluation failed for the named rule.
`ARGON_RUNTIME_EXPLAIN_FAILED`	400	RFD 0046 D3: reconstructing the per-fact proof tree failed for the named relation (e.g. the relation could not be resolved or the materialization erred).
`ARGON_RUNTIME_EXPLAIN_BAD_TUPLE`	400	RFD 0046 D3: an element of the explain request’s `tuple` is not a valid wire value.
`ARGON_RUNTIME_CHECK_VIOLATION`	400	An RFD 0025 delta-guard rejection: the mutation would create a blocking check violation. Atomic — nothing persisted; `error.details.diagnostics` lists the firings.
`ARGON_RUNTIME_ADHOC_TYPE_ERROR`	400	An ad-hoc query/mutation body failed to type-check against the loaded module’s schema; `error.details.diagnostics` lists the firings. The body is never run.
`ARGON_RUNTIME_ADHOC_PREPARATION_FAILED`	400	An ad-hoc query/mutation source could not be parsed/lowered to an executable form (malformed source, no `query`/`derive`/`mutate` item, or a lowering refusal).
`ARGON_RUNTIME_FORK_NOT_DERIVED`	400	A fork operation needs a prior derive that has not run.
`ARGON_RUNTIME_METHOD_NOT_ALLOWED`	405	The path exists but does not support the request method.
`ARGON_RUNTIME_CAPABILITY_DENIED`	403	The request needs a runtime capability (e.g. `fork`, `forget`) the caller/server does not grant.
`ARGON_RUNTIME_ADHOC_DISABLED`	403	The ad-hoc query/mutation surface is disabled on this deployment (RFD 0033): it is restricted to its declared invocables.
`ARGON_RUNTIME_UNKNOWN_ROUTE`	404	No route matches the request path.
`ARGON_RUNTIME_UNKNOWN_QUERY`	404	No declared `pub query` matches the descriptor’s qualified path.
`ARGON_RUNTIME_UNKNOWN_MUTATION`	404	No declared `pub mutate` matches the descriptor’s qualified path.
`ARGON_RUNTIME_UNKNOWN_COMPUTE`	404	No supported pure `pub fn` matches the compute descriptor’s qualified path.
`ARGON_RUNTIME_UNKNOWN_CHECK`	404	The `/v1/checks` `check` filter names no check in the module.
`ARGON_RUNTIME_FORK_NOT_FOUND`	404	The named fork does not exist in this scope.
`ARGON_RUNTIME_REQUEST_TIMEOUT`	408	The request (or the synchronous reasoner) exceeded its wall-clock budget and was abandoned before persisting.
`ARGON_RUNTIME_FORK_CLOSED`	409	The fork has been promoted or aborted and is no longer writable.
`ARGON_RUNTIME_SCOPE_ID_COLLISION`	409	Two distinct scopes hash to the same scope id (a configuration fault).
`ARGON_RUNTIME_SCHEMA_MISMATCH`	409	An artifact’s schema identity does not match the scope’s recorded identity (R-B7); set `ARGON_ACCEPT_SCHEMA_CHANGE=1` to override.
`ARGON_RUNTIME_MODULE_INCOMPATIBLE`	409	A hot-reload candidate is incompatible with live ABox state (removed / changed declarations).
`ARGON_RUNTIME_ADHOC_MULTI_MODULE_UNSUPPORTED`	409	An ad-hoc query/mutation was submitted against a composed/multi-module artifact (declarations span more than one module prefix); a bare body predicate has no single prefix to re-qualify against. A tracked follow-on (RFD 0033, open questions).
`ARGON_RUNTIME_RESULT_TOO_LARGE`	413	An un-paged read exceeded the result-row cap; narrow the request or page it (`page` / `?limit`).
`ARGON_RUNTIME_REQUEST_TOO_LARGE`	413	The request body exceeded the server’s body-size limit (default 4 MiB).
`ARGON_RUNTIME_CHECK_EVAL_FAILED`	500	A check could not be evaluated (a server / artifact fault, not a client error).
`ARGON_RUNTIME_STORAGE_ERROR`	500	The storage backend returned an error during the operation.
`ARGON_RUNTIME_MODULE_NOT_LOADED`	503	No module is currently loaded (a failed load left the prior module active or none present).
`ARGON_RUNTIME_STORAGE_UNREACHABLE`	503	`/readyz` / `/v1/health`: the storage backend is not reachable.

A batch-step failure (POST /v1/batch) rides the same envelope under the step’s own code, with the failing step’s 0-based index added at error.details.batchStep. A 429/load-shedding code is not part of the current surface (the request-timeout and result-row caps are the back-pressure mechanisms).

Keyboard shortcuts

Argon Reference

Runtime error codes