Skip to main content

The KnoxCall response block

When you call a route through KnoxCall, the status, headers and body you get back are your upstream’s, forwarded verbatim. That is deliberate: your code should see what your provider actually said, byte for byte. It leaves one question the response alone cannot answer. A 429 came back — was that your provider’s rate limit, or ours? A 502 — did the call reach them at all? The KnoxCall response block answers it, on every response, without touching the body your provider sent.
The whole x-knox- response namespace is reserved. If your upstream sends a header in it, KnoxCall drops it rather than relaying it. Everything below is always KnoxCall speaking, never something an upstream can forge.

The one check that matters

X-Knox-Upstream-Status is present if and only if a real upstream response was received.
If you wrap a provider SDK, branch on that absence. Without it, a client library reads our 429 as the provider’s and retries against a limit that is not the one refusing it — backing off in the wrong place, for the wrong reason, until the provider’s own limiter finally trips.
X-Knox-Origin says the same thing in a word, for when you are reading curl -i rather than writing code.

Every header

Latency, and what it measured

X-Knox-Latency-Ms cannot mean the same thing on a buffered and a streamed response, so it is labelled rather than left ambiguous:
  • X-Knox-Latency-Phase: complete — the whole body was in hand. The number is the full round trip.
  • X-Knox-Latency-Phase: first-byte — the response is streaming. Headers must be sent before any body byte, so this is time-to-first-byte and the total is not knowable yet.
X-Knox-Upstream-Ms and X-Knox-Overhead-Ms split that time between your provider and us. Both are omitted when the split was not measured rather than estimated — if you see them, they were timed. The upstream clock starts once your provider’s address is resolved, so DNS lookup time counts as KnoxCall overhead, not provider time. The same split is stored on the request’s log row. The log detail page’s Proxy tab shows Proxy Latency as that overhead figure (total minus upstream), so what you read there and what the header said for the same request agree.

Rate limits

Each limiter reports its own window, so three different ceilings do not collapse into one ambiguous pair of numbers:
reset is an ISO-8601 instant. It is absent on the monthly window, which rolls over with your billing period rather than on a fixed clock. The account-wide (tenant) limit is a token bucket, so its window carries a fourth key, appended last so a parser of the first three is unaffected:
  • limit — your plan’s sustained rate, in requests per minute.
  • burst — the most requests admitted at once: the bucket, ten seconds of limit on every plan (17 / 167 / 834 / 1,667 for Free / Starter / Pro / Enterprise).
  • remaining — requests you can send right now. Never more than burst.
  • reset — when the bucket is full again, so never more than about ten seconds away.
A 429 from the tenant limit while you are under your per-minute limit means the burst ran out; X-RateLimit-Layer: tenant and X-RateLimit-Burst on that response say so.
The older X-RateLimit-Limit, X-RateLimit-Tenant-* and X-API-Usage-* headers are still sent and still correct. They are deprecated in favour of the block above — the three families used different names, units and reset formats, and none of them said whether the limit that refused you was KnoxCall’s or your provider’s. Nothing that reads them today needs to change yet.

On errors KnoxCall itself returns

When KnoxCall refuses a call, the body is ours, so the block is repeated there as a knoxcall object alongside the usual error envelope:
The knoxcall key is a sibling of error, not nested inside it, so the existing error envelope is unchanged and a client that does not know about the block simply ignores it.

When KnoxCall itself could not serve the call

If a KnoxCall dependency was unreachable or did not answer in time, the call is refused rather than forwarded unmetered or served from stale data:
dependency is control_plane or rate_limit_store. Treat it like any other 503: wait Retry-After, then retry — the request never reached your provider, so it is safe to resend. It is not a credential problem and it is not a rate-limit hit; do not refresh credentials or back off against your own limits because of it. The official SDKs already do this. On a forwarded response the block stays in the headers only. Your upstream’s body is passed through untouched — it may be JSON, a PDF, an image or a stream, and KnoxCall does not rewrite any of them.