Errors

RORCex uses consistent JSON error envelopes across all endpoints. This page documents every shared error shape. Endpoint-specific errors are noted inline in each endpoint's documentation.

---

Authentication & Authorization

401 — Unauthenticated

No token was supplied, or the token is expired/invalid.

{ "error": "Unauthenticated." }

401 — Wrong token type

A token of the wrong type was presented (e.g., a user token on a service-only endpoint or vice versa).

{ "error": "invalid_token_type" }

403 — Forbidden

The token is valid but the caller lacks the required permission, or the request targets an organization outside the caller's accessible scope.

{ "error": "Forbidden." }

---

Upstream Proxy Errors

Live-proxy read and write endpoints relay requests to the RORC lane software. When the upstream returns a 4xx or 5xx, RORCex mirrors the HTTP status code and wraps the response:

{
  "error": "upstream_error",
  "upstream_status": 500,
  "message": "Upstream returned an unexpected error.",
  "upstream_body": "..."
}

Field	Type	Description
error	string	Always "upstream_error"
upstream_status	integer	HTTP status code returned by the RORC lane
message	string	Human-readable summary
upstream_body	string	Raw response body from the lane (may be empty)

502 — Transport failure

When RORCex cannot reach the lane at all (network timeout, connection refused, etc.) the status is 502 Bad Gateway and the same envelope is returned with upstream_status omitted or set to 0.

---

Store Not Installed

Returned when a requested store_org_id has no active RORCex install, or the install is out of scope for the calling organization.

Status: 404 Not Found

{
  "error": "store_not_found",
  "store_org_id": "org_00000k1L2m3N4o5",
  "message": "No active install found for this store."
}

---

Report Errors

These errors are returned by /v1/reports/{report_id}/run and related run endpoints.

404 — Report not found

The report_id does not match any registered report slug.

{
  "error": "report_not_found",
  "report_id": "sales.nonexistent_report",
  "message": "No report registered for 'sales.nonexistent_report'."
}

422 — Parameter validation failed

The request body does not satisfy the report's parameter_schema. The errors map keys correspond to parameter field names.

{
  "error": "report_param_validation_failed",
  "report_id": "sales.department_performance_by_store",
  "errors": {
    "from": ["The from field must be a valid date in Y-m-d format."],
    "dimension": ["The selected dimension is invalid."]
  }
}

422 — Report execution failed

The report ran but produced no result due to a non-recoverable runtime error. params_echo reflects the parameters that were submitted.

{
  "error": "report_failed",
  "report_id": "sales.department_performance_by_store",
  "message": "Report execution failed.",
  "params_echo": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  }
}

---

CommerceStream Query Errors

Endpoints backed by the CommerceStream materialization (e.g. HQ timeseries and some reports) return this when the materialization query fails. The HTTP status is 422 when the upstream returned a 4xx, otherwise 502.

{
  "error": "cs_query_failed",
  "cs_status": 401,
  "message": "CS materialization query failed: HTTP 401 Unauthorized",
  "cs_body": "..."
}

---

Fan-Out Errors

Returned by the multi-store fan-out endpoints (/v1/fanout/...). A failed preview validation is not an error envelope — it is reported via the dispatch status (preview_failed) in a 200 response; see Fan-out.

404 — Unknown operation type

{
  "error": "fanout_operation_not_found",
  "operation_type": "not_a_real_operation",
  "message": "No fan-out operation registered for 'not_a_real_operation'."
}

422 — Payload validation failed

The payload does not satisfy the operation's schema. errors keys are payload field names.

{
  "error": "fanout_payload_validation_failed",
  "operation_type": "hostcom_batch",
  "errors": {
    "file_id": ["The file_id field is required."]
  }
}

422 — Store out of scope

One or more requested store_org_ids fall outside the caller's accessible scope. Fan-out writes are rejected (not silently narrowed). offending_stores lists the out-of-scope stores.

{
  "error": "fanout_store_out_of_scope",
  "operation_type": "hostcom_batch",
  "offending_stores": ["org_00000z9Y8x7W6v5"],
  "message": "One or more stores are outside the caller's scope."
}

409 — Dispatch not previewed

Returned when committing a dispatch that is not in a committable state (e.g. its preview failed or it was already committed). status is the dispatch's current status.

{
  "error": "fanout_not_previewed",
  "dispatch_id": "01J9XR4K7P8VN2YQ6ZB3TGD0WC",
  "status": "preview_failed",
  "message": "Dispatch is not in a committable state."
}

---

Hostcom Authoring Errors

These errors are returned by the hostcom file authoring endpoint (POST /v1/hostcom/files/author).

422 — Record validation failed

A record in the submitted hostcom payload failed field-level validation. row_index is zero-based. The errors map keys are the snake_case row field names within the failing record.

{
  "error": "hostcom_record_validation_failed",
  "record_type": "ProdRetail",
  "row_index": 0,
  "errors": {
    "retail_price": ["The retail_price field must match the pattern xxxxx.xx."],
    "product_code": ["The product_code field is required."]
  },
  "message": "Row 0 of ProdRetail failed validation."
}

422 — Unknown record type

The hostcom payload contains a record type that RORCex does not recognise. supported_types lists the valid record types.

{
  "error": "hostcom_unknown_record_type",
  "record_type": "NotARealRecord",
  "supported_types": ["ProdRetail", "ItemDeal", "Department", "ProdMaint", "Vendor", "VendorItem", "..."],
  "message": "Unknown record type 'NotARealRecord'."
}

422 — Unorderable record

The record type is known but the (record_type, action_code) pair cannot be ordered into the hostcom file (e.g. an unsupported action for that type).

{
  "error": "hostcom_unorderable_record",
  "record_type": "ProdNonRtl",
  "action_code": "A",
  "message": "Record type 'ProdNonRtl' does not support action 'A'."
}