Adapters ↔ Orchestration crosswalk

A practical mapping between orchestration catalogs (errors, warnings, metrics) and HTTP adapter surfaces (status codes, headers, response bodies). Goal: consistency and easier client handling.

Errors → HTTP status + body

• orc/error/invalid_request → 400 Bad Request

  • body: { error: { code: "invalid_request", message, details? }, request_id }

• orc/error/unauthorized → 401 Unauthorized

  • headers: WWW-Authenticate where applicable

• orc/error/forbidden → 403 Forbidden

• orc/error/not_found → 404 Not Found

• orc/error/rate_limited → 429 Too Many Requests

  • headers: Retry-After, X-Backoff-Hint?

• orc/error/upstream_timeout → 504 Gateway Timeout

• orc/error/internal → 500 Internal Server Error

Body contract: schema-shaped error body as documented in http-adapter.md (stable v0).

Warnings → HTTP headers

• X-Warning-Code: <catalog_id> (e.g., orc/warn/degraded)
• X-Warning-Action: <action> (e.g., retry_later|minimal_reply|fallback_path)
• X-Warning-Details: JSON-encoded compact details (optional)

Common cases:

• orc/warn/degraded → minimal reply path, X-Warning-Action: minimal_reply
• orc/warn/backpressure → suggest retry, X-Warning-Action: retry_later
• orc/warn/privacy_redaction → inform client summaries redacted

Metrics → HTTP headers

• X-Request-ID: correlation id
• X-Budget-Used: numeric budget share (0..1)
• X-Orchestrator-Time-Ms: end-to-end time inside orchestrator
• X-Adapter-Time-Ms: adapter overhead
• X-L4-Time-Ms: Experience retrieval time
• X-L4-Share: share of total time (0..1)

Minimal vs full replies

• Minimal: fewer slices/fields; clients should not assume fixed count.
• Signal via X-Warning-Code=orc/warn/degraded, X-Warning-Action=minimal_reply.

Backpressure 202 example

• Status: 202 Accepted
• Body: { queued: true, eta_ms: <int>, request_id }
• Headers: X-Warning-Code=orc/warn/backpressure, X-Warning-Action=retry_later

Refer to: adapters/http-adapter.md for canonical shapes and examples.