cyoda error reference

cyoda-go version 0.6.2

errors

NAME

errors — error model and code catalogue.

SYNOPSIS

REST responses use RFC 9457 Problem Details:

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "ENTITY_NOT_FOUND: entity id=abc not found",
  "instance": "/api/v1/entities/abc",
  "properties": {
    "errorCode": "ENTITY_NOT_FOUND",
    "retryable": false
  }
}

gRPC error envelope example (returned in the CloudEvent response payload):

{
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "entity id=abc not found",
    "retryable": false
  }
}

The gRPC response also carries errorCode and retryable in trailer metadata.

DESCRIPTION

Every error response from the Cyoda REST API carries a structured errorCode in the properties object. Multiple codes may share the same HTTP status. Programmatic handling keys on errorCode, not HTTP status.

The retryable property is present and true only when the operation is safe to retry as-is (e.g., transient cluster conditions). When absent or false, the request or system state must change before retrying.

5xx responses include a ticket UUID for server-side log correlation. Share this value when reporting issues.

CYODA_ERROR_RESPONSE_MODE controls 5xx detail level. sanitized (default): generic message plus ticket UUID. verbose: internal error detail included in the response body; intended for development environments only.

ERROR CODE INDEX

errors.BAD_REQUEST — 400 — not retryable — request body, query parameter, or header is malformed or structurally invalid
errors.CLUSTER_NODE_NOT_REGISTERED — 503 — retryable — target cluster node is not present in the gossip registry
errors.COMPUTE_MEMBER_DISCONNECTED — 503 — retryable — compute member holding a processor assignment has disconnected
errors.CONFLICT — 409 — retryable — optimistic concurrency check failed; entity was modified concurrently
errors.DISPATCH_FORWARD_FAILED — 503 — retryable — HTTP forwarding call to peer node failed
errors.DISPATCH_TIMEOUT — 503 — retryable (see note) — compute member did not respond within the dispatch timeout; completion on the remote node is not guaranteed
errors.ENTITY_NOT_FOUND — 404 — not retryable — entity UUID does not exist or is not accessible to the caller
errors.EPOCH_MISMATCH — 409 — retryable — writing node’s cached shard epoch is stale; another node has since taken ownership
errors.FORBIDDEN — 403 — not retryable — authenticated caller lacks the required role or the tenant does not match
errors.HELP_TOPIC_NOT_FOUND — 404 — not retryable — help topic path does not resolve to any topic in the tree
errors.IDEMPOTENCY_CONFLICT — 409 — not retryable — request with the same idempotency key was received but payload differs from the original
errors.MODEL_NOT_FOUND — 404 — not retryable — referenced entity model does not exist in the tenant’s model registry
errors.MODEL_NOT_LOCKED — 409 — not retryable — model exists but is not in LOCKED state; entity writes require a locked model
errors.NO_COMPUTE_MEMBER_FOR_TAG — 503 — retryable — no live cluster node advertises the compute tag required by the processor
errors.NOT_IMPLEMENTED — 501 — not retryable — endpoint is defined but has no functional implementation in this version
errors.POLYMORPHIC_SLOT — 400 — not retryable — payload discriminator selects an unrecognised variant or fails the variant schema
errors.SEARCH_JOB_ALREADY_TERMINAL — 409 — not retryable — operation attempted on a search job that has already completed, failed, or been cancelled
errors.SEARCH_JOB_NOT_FOUND — 404 — not retryable — referenced search job does not exist in the current tenant
errors.SEARCH_RESULT_LIMIT — 400 — not retryable — search query matched more results than the server-enforced maximum
errors.SEARCH_SHARD_TIMEOUT — 503 — retryable — one or more search shards did not respond within the configured timeout
errors.SERVER_ERROR — 500 — retryable with caution — unclassified internal error; response includes ticket UUID for log correlation
errors.TRANSACTION_EXPIRED — 400 — not retryable — transaction token’s exp claim is in the past
errors.TRANSACTION_NODE_UNAVAILABLE — 503 — retryable — cluster node that owns the open transaction is unreachable
errors.TRANSACTION_NOT_FOUND — 404 — not retryable — transaction ID does not correspond to an active transaction on this node
errors.TRANSITION_NOT_FOUND — 404 — not retryable — requested workflow transition is not defined for the entity’s current state
errors.TX_CONFLICT — 409 — retryable — transaction aborted due to storage-level serialization conflict
errors.TX_COORDINATOR_NOT_CONFIGURED — 503 — not retryable — distributed transaction coordinator is disabled or misconfigured on this node
errors.TX_NO_STATE — 404 — not retryable — coordinator has no state record for the given transaction ID
errors.TX_REQUIRED — 400 — not retryable — operation requires a transaction context but none was provided
errors.UNAUTHORIZED — 401 — not retryable — Authorization header is missing, token is expired, signature is invalid, or issuer is untrusted
errors.VALIDATION_FAILED — 400 — not retryable — payload is structurally valid JSON but fails the model’s schema or workflow validation rules
errors.WORKFLOW_FAILED — 400 — not retryable — workflow processor or guard condition returned a failure during state transition
errors.WORKFLOW_NOT_FOUND — 404 — not retryable — workflow definition referenced by the entity model does not exist

Subtopics

cyoda help errors BAD_REQUEST — Fired when the server cannot parse or structurally process the incoming request. Common triggers include invalid JSON, missing required fields, unsupported format specifiers, or mutually exclusive parameters being set simultaneously.
cyoda help errors CLUSTER_NODE_NOT_REGISTERED — The request was routed to or requires a specific cluster node that is not present in the registry. Occurs during startup, rolling restarts, or after a node failure before the gossip layer has converged.
cyoda help errors COMPUTE_MEMBER_DISCONNECTED — The compute member responsible for executing a processor or workflow step disconnected before completing the operation. The task may or may not have been executed.
cyoda help errors CONFLICT — The server detected that the entity was modified by another writer between the time it was read and the time the current write was committed. Normal outcome under concurrent load.
cyoda help errors DISPATCH_FORWARD_FAILED — The cluster dispatcher attempted to forward a processor invocation or criteria evaluation to a peer node but the HTTP call to that peer failed (network error, peer crash, or connection refused). The operation has not been executed on the target node.
cyoda help errors DISPATCH_TIMEOUT — A workflow processor or criteria evaluation was dispatched to a compute member but the response did not arrive within the dispatch timeout window. The underlying task may or may not have completed on the remote node.
cyoda help errors ENTITY_NOT_FOUND — No entity with the given ID exists in the tenant’s data store, or the entity existed at a point-in-time that precedes the requested snapshot. Also returned for audit log lookups when the specified event or message cannot be found.
cyoda help errors EPOCH_MISMATCH — Shard ownership is tracked by an epoch counter that increments whenever the cluster re-partitions. A write is rejected with this error when the writing node’s cached epoch is stale — another node has since taken ownership of the shard. This prevents split-brain writes.
cyoda help errors FORBIDDEN — The request was authenticated successfully but the caller’s JWT claims do not include the role required by the endpoint (for example, admin is required for administrative operations). Tenant mismatch — where the caller’s tenant does not match the resource — also produces this error.
cyoda help errors HELP_TOPIC_NOT_FOUND — Returned by GET {ContextPath}/help/{topic} when {topic} is well-formed (matches [A-Za-z0-9._-]+) but does not resolve to any topic in the tree. Clients should GET {ContextPath}/help to discover available topic paths.
cyoda help errors IDEMPOTENCY_CONFLICT — The idempotency key is supplied via the Idempotency-Key HTTP header on collection create and update requests. See crud for the request shape.
cyoda help errors MODEL_NOT_FOUND — The entity type or model name specified in the request does not exist in the tenant’s model registry. Occurs when creating entities with an unknown type, importing data that references a missing model, or performing model lifecycle transitions on a model ID that does not exist.
cyoda help errors MODEL_NOT_LOCKED — Entity creation and bulk write operations require the model to be in the LOCKED lifecycle state. Models in DRAFT or unlocked-for-editing state reject writes to prevent schema changes from affecting in-flight data.
cyoda help errors NOT_IMPLEMENTED — The route is defined and accepted by the server but the handler returns this error because the feature is pending implementation. Distinct from a 404 — the endpoint exists without a functional implementation.
cyoda help errors NO_COMPUTE_MEMBER_FOR_TAG — Workflow processors are dispatched to nodes that advertise matching compute tags. When no node with the required tag is alive in the cluster within the configured wait timeout (CYODA_DISPATCH_WAIT_TIMEOUT), the operation is rejected with this error.
cyoda help errors POLYMORPHIC_SLOT — A model can define polymorphic slots — fields whose schema varies based on a discriminator value. This error fires when the payload’s discriminator selects a variant whose schema the provided data fails to match, or when the discriminator value itself is unrecognised.
cyoda help errors SEARCH_JOB_ALREADY_TERMINAL — Search jobs are long-running asynchronous operations. Once a job reaches a terminal state it cannot be cancelled, resumed, or otherwise modified. This error is returned when such an operation is attempted on a finished job.
cyoda help errors SEARCH_JOB_NOT_FOUND — Polling a search job by ID returns this error when the job ID is unknown or belongs to a different tenant. Jobs are tenant-scoped; a valid job ID from one tenant is not visible to another.
cyoda help errors SEARCH_RESULT_LIMIT — The server imposes an upper bound on the number of results returned per page and per job to protect cluster resources. Returned when the request exceeds this limit — either by requesting too large a page size or by the matched result count exceeding the cap.
cyoda help errors SEARCH_SHARD_TIMEOUT — Distributed search fans out to multiple shards in parallel. If any shard does not return results before the search timeout expires, the job is marked failed and this error is returned. Occurs under high load, during partial cluster degradation, or with expensive queries.
cyoda help errors SERVER_ERROR — The server encountered an unclassified internal error. The response body contains a ticket UUID that correlates with the server-side error log. No internal details are exposed in the response.
cyoda help errors TRANSACTION_EXPIRED — Transaction tokens are short-lived bearer tokens issued when a transaction is opened. This error fires when the token’s exp claim is in the past at the time the proxy validates it. The transaction itself may still be active server-side, but the token is no longer valid for routing.
cyoda help errors TRANSACTION_NODE_UNAVAILABLE — Transaction state is pinned to the node that opened it. If that node crashes or becomes unreachable while the transaction is in progress, subsequent requests using the transaction token are rejected with this error because the proxy cannot forward them to the owner.
cyoda help errors TRANSACTION_NOT_FOUND — The transaction ID supplied in the request does not correspond to an active transaction. The transaction may have been committed, rolled back, expired, or may never have existed. Also occurs when a request is mis-routed to a node that never opened the transaction.
cyoda help errors TRANSITION_NOT_FOUND — Entity workflow state machines define explicit transitions between states. This error fires when a transition is triggered that does not exist in the model’s workflow definition for the entity’s current state. Also occurs when the transition name is misspelled or when the entity is in a terminal state that allows no further transitions.
cyoda help errors TX_CONFLICT — The underlying storage detected a serialization failure (e.g., PostgreSQL error 40001 or 40P01) and aborted the transaction. Normal occurrence under concurrent write load when using serializable or repeatable-read isolation.
cyoda help errors TX_COORDINATOR_NOT_CONFIGURED — Certain operations that span multiple storage shards require a distributed transaction coordinator. This error is returned when such an operation is attempted on a node where the coordinator component is disabled or misconfigured.
cyoda help errors TX_NO_STATE — The two-phase commit coordinator tracks per-transaction state (prepared, committed, aborted). This error is returned when a commit or abort instruction references a transaction for which no state record exists, because the transaction was never prepared or was already cleaned up.
cyoda help errors TX_REQUIRED — Certain write operations that require atomic multi-step coordination mandate a transaction context. Returned when such an operation is called without a transactionId header or query parameter.
cyoda help errors UNAUTHORIZED — Returned when the Authorization header is missing, the bearer token is expired, the token signature is invalid, or the token was issued by an untrusted issuer. Also returned when a request reaches a protected route with no identity context established by the auth middleware.
cyoda help errors VALIDATION_FAILED — Unlike BAD_REQUEST (which covers parse failures), this error is returned when the payload is parseable but violates the registered model schema — for example, a required field is missing, a value is out of the allowed range, or a workflow guard condition is not satisfied. The error detail includes the specific validation failure.
cyoda help errors WORKFLOW_FAILED — During an entity create or transition operation the associated workflow processors (pre-processors, post-processors) or guard conditions ran but one of them signalled failure. The failure message from the processor is included in the error detail.
cyoda help errors WORKFLOW_NOT_FOUND — Entity models reference a workflow by name to govern state transitions. This error is returned when the named workflow cannot be found in the tenant’s workflow registry, during entity type registration or when a model references a workflow that was deleted.

Raw formats

/help/errors.json — full descriptor (matches GET /help/{topic} envelope)
/help/errors.md — body only