Error Contracts & Status Codes

Errors share one envelope:

{"error": {"message": "...", "type": "invalid_developer_key", "code": 401}}

/v1/execute differs. A validation failure is {"detail": {"error": "...", "field": "input.messages"}} and a locked-skill override is {"detail": {"error": "skill_locked", "locked": [...]}}. Both still carry x-ace-error (request_error and skill_locked respectively).

x-ace-error — whose error this is. Every error ACE originated carries the response header x-ace-error: <type>, on every surface (/v1/chat/completions, /v1/responses, /v1/execute, /anthropic/v1/messages and count_tokens, /v1/messages, /azure/openai/…, /gemini/v1beta/…, /bedrock/…), whatever envelope the body wears — the value is the type from the table above, plus the values below for refusals that have no typed envelope of their own. It is absent on a vendor error relayed from upstream — a real provider 429, a provider 401 for a bad pass-through key, a ValidationException AWS itself returned — so absence is the signal: no x-ace-error, the provider said this, and its own type and code mean what they say. A retry classifier that reads the header first can terminate on a provider auth error while re-minting an ACE key on invalid_developer_key, and back off on a provider rate limit while surfacing budget_exhausted to a human. The header only ever adds: no body, status or type changed when it was introduced. Engine-raised 5xx that summarize an upstream failure — 502 all upstreams failed, an upstream read timeout, a dispatch-side shed — do not carry it. Four 5xx do, because each is ACE's decision about ACE rather than a report about the provider: 503 overloaded (ACE's own capacity), 504 store_timeout (ACE's own store), 502 upstream_truncated (the provider's 2xx arrived unparseable and ACE refused to relay it) and 504 gateway_timeout (ACE's clock). A failure after the status line has left — a mid-stream error event — cannot carry a header at all.

Guardrail detected values. Regex stage: instruction_override, role_reassignment, secret_exfiltration, system_prompt_probe. Classifier stage: learned_injection. The four regex values come from the always-on stage. learned_injection comes from the optional classifier and only appears on a deployment that has moved it out of its default shadow mode (ACE_GUARDRAILS_MODEL_MODE=enforce). In shadow — the default — the classifier never produces a 400 and never alters the response.

ACE never blocks traffic on its own accounting. No spend threshold, quota or internal limit turns a request into an error. Whenever ACE cannot compute — a metering ceiling, a telemetry blip, a skill that fails to evaluate — it degrades to direct passthrough: relayed straight to your provider, pipeline bypassed, normal 200, upstream body untouched. Errors originate at the edge (auth) or upstream (provider), never from the optimization layer.

Bypass triggers: Skill latency ceiling exceeded — a stage that has not answered inside its per-request wall-clock ceiling (250 ms acting, 50 ms shadow) is shed and the response names it: ceiling_exceeded, overloaded or loop_stalled on that stage's header and trace. Per request, never cumulative; nothing to reset.; Gateway panic / uncaught 500; Redis, Qdrant or TimescaleDB unreachable. Observable as: x-ace-served-by: direct_passthrough; x-ace-warnings: _passthrough; Logged to request_log.error_detail.