[Discussion]Configurable error handling and fault sequences for the API Platform gateway

[SavinduDimal]

Problem

When a policy or guardrail rejects a request, the gateway returns a status code and nothing else happens. A guardrail rejection produces a 422, an authentication failure a 401, and the interaction ends there.

Two distinct needs come out of this, and separating them is what makes the options below tractable:

1. Shaping the error — control the body, media type and status code the client receives, so an error looks like part of the API's contract rather than a gateway artefact.
2. Acting on the error — do something when a request fails: publish an event to a SIEM or event bus, notify a webhook, increment an external counter.

Both are in scope. They are complementary rather than alternatives, and the options below are grouped accordingly.

Error sources

Any design here is constrained by where the error originates, because the four sources are handled at different layers of the gateway.

flowchart TB
    Client(["Client"]) --> Match{"Route matched?"}
    Match -- "no" --> D["SOURCE D — no route<br/>404, body determined at deploy time"]
    Match -- "yes" --> Chain{"Policy chain outcome"}
    Chain -- "rejects" --> A["SOURCE A — gateway/policy error<br/>401 / 403 / 422 / 429 / 500"]
    Chain -- "continues" --> Up["Router → upstream"]
    Up -- "unreachable / timeout" --> C["SOURCE C — router local reply<br/>503 / 504, body determined at deploy time"]
    Up -- "4xx / 5xx" --> B["SOURCE B — backend error"]

Loading

Sources A and B pass through the policy engine on every request, so per-request values are available and policy code can run. Sources C and D never reach the engine: the router generates those responses itself from a body determined when the configuration was deployed, and no policy chain is selected for an unmatched route. That distinction determines what each option can and cannot cover.

Option 1 — Declarative error-response configuration

Addresses need 1. A global document plus a per-API section, both shaped like an OpenAPI Responses Object, customising the body, media type and status code per error status.

spec:
  errorResponses:
    responses:
      "401":
        content:
          application/json:
            example: { code: 401, message: "Authentication required", requestId: "${requestId}" }
      "504":
        x-status-code-override: 502
        content:
          application/json:
            example: { code: "${statusCode}", message: "Upstream did not respond" }

The property relevant to the options below is that this is a renderer: it resolves an entry, negotiates the media type, substitutes placeholders and replaces the body. It performs no I/O. For sources C and D the body is produced when configuration is deployed rather than per request, which is why request-scoped placeholders such as ${requestId} cannot carry values for those sources. The option therefore addresses need 1 across all four sources, and does not address need 2.

Option 2 — Fault sequence (proposed for need 2)

A per-API, ordered list of policies that executes only when a request fails.

spec:
  policies:
    - name: regex-guardrail
      version: v1

  faultSequence:
    - name: log-message
      version: v1
    # Note the `response:` block. This policy participates in the response phase only
    - name: interceptor-service
      version: v1
      params:
        response:
          url: https://siem.internal.example/gateway-faults
    - name: set-headers
      version: v1
      executionCondition: "response.ResponseStatus >= 400"
      params:
        response:
          headers:
            - name: x-fault-ref
              value: contact-support

The sequence executes over the error response, using the same contracts as a response-phase policy. The consequence is that no fault-specific policy type is required and the existing policy catalogue works on the fault path unchanged. Entries are validated with the same names, versions and parameter schemas as normal policies.

Which function an entry is invoked through is resolved per entry, because the catalogue is split between the two response contracts:

Contract implemented	Examples
OnResponseHeaders	set-headers, remove-headers, cors, basic-ratelimit, mcp-ratelimit
OnResponseBody	interceptor-service, and every response guardrail (word-count, regex, content-length, url, ...)
Both	log-message, advanced-ratelimit, token-based-ratelimit

An entry is dispatched through the body contract when it implements one, and through the header contract otherwise. This is not a detail: a sequence supporting only one contract would silently skip roughly half the catalogue — including interceptor-service, the policy that most directly satisfies "notify a third party" — with no error raised, because a policy that does not implement the expected contract is simply never called.

The body contract is preferred where available because it is a superset: it carries the error body, so an entry can transform the error (wrap it, lift fields out of it) rather than only replace it. Entries execute one at a time so declaration order holds across a sequence mixing both kinds.

Trigger points

A single trigger cannot cover the errors the gateway produces, so there are three.

flowchart TB
    Chain["Request policy chain"] -- "policy rejects the request" --> SC["Gateway builds the error response"]
    SC --> T1["T1 — the gateway generated the error"]
    Chain -- "continues" --> Resp["Response header phase"]
    Resp --> Body["Response BODY phase"]
    Body --> Q{"who produced the error?"}
    Q -- "a response-body policy<br/>overrode the status" --> T3["T3 — response-body rejection"]
    Q -- "backend or router,<br/>passing through" --> T2["T2 — pass-through error"]
    Q -- "no error" --> Ok["normal response — sequence never runs"]
    T1 --> FS["FAULT SEQUENCE, in declaration order"]
    T2 --> FS
    T3 --> FS

Loading

T1 is required because the response phase is not reached once a policy has rejected a request; without it a guardrail 422 on the request path would never enter the sequence.

T2 covers errors the gateway did not generate — a backend error passing through, or a router local reply (503/504), which does traverse the external processor.

T3 covers a response-body policy rejecting a response. It needs its own trigger because such a policy rejects by overriding the status rather than short-circuiting the chain, which is what T1 detects; and the override happens after the response-header phase, where the status was still the upstream's success value. Response guardrails reject exactly this way, so without T3 a guardrail rejecting a response would be invisible.

T2 and T3 both run in the response-body phase, so body-contract entries receive the error body. They are distinguished by who produced the error, not by where they run — and that distinction is what keeps the threshold rule below correct. Running the sequence in the body phase requires response-body processing to be enabled for the route, so attaching a fault sequence enables it; otherwise the sequence would never fire for an API whose own policies do not need the body.

Under T2, an entry with no executionCondition runs only at status 500 and above. A 404 for a missing record is routine REST traffic rather than a fault, and firing on all of them would make the feature noisy from the first deployment; an entry opts into 4xx explicitly. T1 and T3 are exempt, since an error the gateway generated is a fault by construction — and a guardrail rejection is a 4xx.

What a fault policy is told

Beyond the error itself, each entry receives fault metadata: the trigger, the phase, the status, the upstream's status before any policy changed it, and which policy caused the failure. That last field is what turns a notification from "a 422 happened" into "word-count-guardrail rejected this response".

Attribution is deliberately absent under T2: no policy causes a backend error or a router local reply, and naming one would be misleading — the trigger already identifies the kind of error.

Coverage: sources A, B and C. Source D is not covered, because no API matched and therefore no per-API sequence can be selected.

Behaviour

• Never runs on a successful response. Fault entries are held separately from policies, so they cannot execute in the normal request or response phases.
• Runs at most once per request, which prevents an error raised inside the sequence from re-entering it.
• A failing entry never fails the request — the client receives the original error.
• An unresolvable entry is rejected at deployment; one that cannot be initialised is skipped with a warning, leaving normal traffic unaffected.
• An entry may replace the response entirely, so an external service can determine what the client sees. An entry on the body contract may also transform the existing error rather than replacing it.
• Entries must be response-phase policies, since the sequence operates on the error response. A request-phase-only policy is not eligible — the respond policy, for instance, cannot be used in a fault sequence.
• Notifications should be asynchronous by default. A fault sequence runs when the system is already degraded, so a synchronous outbound call converts a fast error into a slow one, once per failed request.
• An error raised while a response is being streamed is not covered. By the time a chunk has been forwarded, the status and headers are already with the client, so the error cannot be reshaped — the protocol offers no way to retract them. A notification-only hook for that case is possible, but it must be labelled as such: an entry that tried to replace the response there would appear to work and silently not.

Option 3 — Fault events through the access-log pipeline

Also addresses need 2, by a different route: emit a fault event from the existing analytics pipeline and add a configurable webhook publisher alongside the existing publishers.

Because that pipeline is driven by router access logs rather than by the policy engine, it is the only mechanism that observes all four sources, including the no-route 404 — and also the only one that cannot identify which policy failed without additional metadata being attached. It is global rather than per-API, runs after the response has been sent, and does not execute user-supplied logic.

That makes it complementary to Option 2 rather than a replacement: Option 2 for per-API logic that may influence the response, Option 3 for uniform fault telemetry across every source.

Option 4 — Extend the error-response document with side effects

Adding an onFailure block to Option 1's document is the obvious shortcut, and is not recommended. That renderer currently cannot fail; giving it an outbound call would make every error response inherit a timeout, a retry policy and a new failure mode, on the path that is already degraded. For sources C and D the body is produced at deployment time, so there is no per-request execution to attach a side effect to.

Comparison

	Option 1 — response config	Option 2 — fault sequence	Option 3 — fault events	Option 4 — extend Option 1
Need addressed	Shape the error	Act on the error	Act on the error	Both, in theory
Source A — request phase	Yes	Yes	Yes	Yes
Source A — response body	Yes	Yes	Yes	Partial
Source A — while streaming	Yes	No	Yes	No
Source B	Yes, opt-in	Yes	Yes	Partial
Source C	Yes	Yes	Yes	No
Source D	Yes, global only	No	Yes	No
Per-API	Yes	Yes	No	Yes
Runs user logic	No	Yes	No	No
Reuses existing policies	n/a	Yes, both response contracts	No	No
Can transform an error	Replaces only	Yes, on the body contract	No	Replaces only
Blocks the response	No	Configurable	Never	Would

Source A is split into three rows deliberately. It is not uniformly covered by Option 2, and the distinction is not visible from the outside: a request-phase rejection and a response-body rejection reach the sequence by different triggers, and an error raised mid-stream cannot reach it at all.

Open questions

• Is the primary requirement observability or control? Publishing an event is observability and could be served more cheaply by Option 3. Calling out and letting the response depend on the answer is control, and needs Option 2.
• Asynchronous notification is at-most-once and unbounded under a burst of failures. A bounded queue with an explicit drop policy is needed before this is offered to customers — what are the expectations around delivery guarantees?
• The notification destination is operator-supplied and dialed by the gateway, so it requires validation of the resolved address at connection time rather than a scheme check alone.
• A guardrail's fault notification must not carry the blocked content by default, since that is precisely the data the guardrail exists to prevent leaving. Should including it be possible at all, even as an explicit opt-in? Note this becomes sharper on the body contract, where the entry now receives the error body directly.
• Should a fault entry be distinguishable from an ordinary response policy at the type level? Today the two are identical, so nothing prevents a notification policy being configured under policies, where it would fire on every successful response instead of only on failures. A dedicated OnError contract would make "faults only" a guarantee rather than a convention — but adopting it as the only contract would forfeit reuse of the existing catalogue, which is Option 2's main advantage. An optional additional contract, checked before the two response contracts, would give the guarantee without that cost.
• Should the fault sequence run for a response that is being streamed, in notification-only form? It is the one part of source A the mechanism cannot cover, and streaming responses are exactly where the LLM-facing guardrails are used.