Errors and request ids

The error envelope

Every error from the order engine surfaces is JSON with at least these fields:

Field	Meaning
code	Stable, machine-readable code, for example version_mismatch. Branch on this.
message	Human-readable explanation. Log it; do not parse it.
requestId	The request id, the same value as the X-Request-Id response header.

Some responses add detail:

Field	Where
details	Order operations and group surfaces: every validation issue, or the rule that refused the request.
issues	Quote store and configuration validation: the list of issues with their paths.
error	Kept for existing clients. On most surfaces it repeats the code; on the quote store it is a message.

POST/order-orchestration/trips/TRP-3751D490D704/purchase-ordersA request that fails validation

Request

curl -X POST "$BASE/order-orchestration/trips/TRP-3751D490D704/purchase-orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Request-Id: req-0037" \
  -H "Content-Type: application/json" \
  -d '{
  "channel": "app",
  "moment": "pre_trip",
  "currency": "EUR",
  "lines": [
    {
      "productType": "excursion",
      "quantity": 0,
      "amountMinor": -100
    }
  ]
}'

Response

HTTP/1.1 400
X-Request-Id: req-0037

{
  "error": "invalid_request",
  "message": "lines.0.productCode: Required",
  "code": "invalid_request",
  "requestId": "req-0037"
}

POST/order-orchestration/quotationsA channel that is not in the orchestration configuration

Request

curl -X POST "$BASE/order-orchestration/quotations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Request-Id: req-0038" \
  -H "Content-Type: application/json" \
  -d '{
  "channel": "kiosk",
  "createdBy": {
    "actorRef": "CUST-20419",
    "kind": "customer"
  },
  "customerRef": "CUST-20419",
  "anchor": {
    "productType": "cruise",
    "productId": "MED7-2027-04-12",
    "unitRef": "BALCONY-B2",
    "departureAt": "2027-04-12T17:00:00Z",
    "returnAt": "2027-04-19T08:00:00Z",
    "market": "IT"
  },
  "quote": {
    "quoteRef": "Q-2027-58214",
    "quoteVersion": 0,
    "currency": "EUR"
  }
}'

Response

HTTP/1.1 422
X-Request-Id: req-0038

{
  "error": "unknown_channel",
  "message": "unknown channel 'kiosk'",
  "code": "unknown_channel",
  "requestId": "req-0038"
}

Status codes

Status	Meaning	Retry?
200, 201	Success. 201 when a resource was created.	—
202	Accepted: an inbound event was received and logged; the body says how it was applied.	—
400	The request is malformed or failed validation (invalid_request, invalid_if_match, invalid_idempotency_key).	No; fix the request.
401	Missing, invalid or expired token (unauthenticated).	After obtaining a valid token.
403	The token may not do this (forbidden, scope_forbidden, not_creator, channel_not_allowed).	No.
404	The resource does not exist, or the surface is not enabled for the tenant (not_enabled and the like).	No.
409	The request conflicts with the current state (invalid_transition, already_converted, version_conflict, idempotency_in_progress).	Only idempotency_in_progress, after Retry-After. Otherwise read the resource again.
412	The If-Match version is stale (version_mismatch).	After reading the resource again.
422	The request is valid but breaks a business rule (unknown_channel, missing_fields, overpayment, idempotency_key_reused).	No; change the request.
500	Unexpected failure (internal).	Yes, with the same Idempotency-Key.
503	A dependency is unavailable (handover_source_unavailable).	Yes, with backoff and the same Idempotency-Key.

The API reference lists the codes each operation can return.

Request ids

Send a correlation id on every request and log it on both sides:

X-Request-Id: mule-2f8c1a7e-0001

Rule	Value
Accepted headers	X-Request-Id, or X-Correlation-Id.
Format	8 to 128 characters of A-Z a-z 0-9 . _ : -. A value outside this format is ignored and a new id is generated.
Response	Every response carries X-Request-Id: your value, or a generated UUID. Every error body carries it as requestId.

Quote the request id when you raise a support case; it identifies the request in the service's logs and traces.

Validation detail

Order orchestration names the first failing field in message (for example lines.0.productCode: Required). Order operations and group surfaces return every issue in details. The quote store returns every issue in issues, with code: invalid_input.