Calling a REST operation

What goes through, what is removed, what is refused, and the headers the gateway adds to the response.

Product side: API gateway; operations side: Serving your first API.

The request

Element	Treatment
Headers the contract declares	Relayed
Protocol headers (Accept*, Content-*, If-*, Range, Cache-Control, Idempotency-Key, traceparent, X-Request-Id, User-Agent)	Relayed
Authorization	Relayed toward a secured operation; an API key never is
Any other header	Removed, without an error
Forwarded, X-Forwarded-*	Rewritten by the gateway; yours are ignored
Undeclared query parameter	400 malformed_request, the parameter named
Body or parameter outside the schema	422 invalid_request; the errors extension names each field
Body too large	413 payload_too_large

{
  "type": "https://flexway.dev/problems/invalid_request",
  "title": "The request does not match the contract",
  "status": 422,
  "code": "invalid_request",
  "errors": [ { "field": "body.quantity", "rule": "must be >= 1", "code": "minimum" } ],
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Correlation

Send traceparent (W3C) to join your trace to the gateway's, and X-Request-Id for an id of your own: both are relayed to the API, and a refusal returns them in trace_id and request_id. Quote them in a ticket - the detail is in the operator's log.

CORS

A browser application on another origin must be allowed by the operator. An origin not allowed gets 403; the OPTIONS preflight is answered by the gateway. For gRPC-Web, see gRPC.

Caching

Response header	Meaning
Flexway-Cache: hit and Age	Served from the gateway's cache, the API was not called
Flexway-Cache: miss	Relayed, and offered to the cache
304 Not Modified	Your If-None-Match matches the stored ETag

A cache hit still counts against your rate and quota. Only operations that declare it are cached; an authenticated response only per tenant and per person.

Announced degradation

Flexway-Degraded says a response is served degraded: circuit-open (the upstream is cut off), upstream-saturated, shedding (on a 503 overloaded), backend-fallback (inference served by a fallback backend). It is not an error; log it.