Document updated on Oct 19, 2020
When consuming content through KrakenD, the status code returned to the client depends on the chosen configuration. Three different approaches impact status codes:
no-op encoding is set, the following status codes are the default behavior of any KrakenD endpoint.
|At least one backend returned a 200 or 201 status code on time. Completeness information provided by the
404 Not Found
|The requested endpoint is not configured on KrakenD
400 Bad Request
|Client made a malformed request, i.e. json-schema validation failed
|Client sent an invalid JWT token or its claims
|The user is allowed to use the API, but not the resource, e.g.: Insufficient JWT role, or bot detector banned it
429 Too Many Requests
|The client reached the rate limit for the endpoint
503 Service Unavailable
|All clients together reached the configured global rate limit for the endpoint
500 Internal Server Error
|Default error code, and in general, when backends return any status above
500 Internal Server Error by default?
In most cases, when there isn’t a happy path, you’ll see KrakenD returning a
500 Internal Server Error. When KrakenD needs to combine in the final gateway response, there is no way to properly distinguish the status code from the backend and the one from the gateway itself. That’s why all errors external to KrakenD are translated into a
500 Internal Server Error.
To offer a gracefully degraded service when some backends fail, we leave the decision to the client on what to do by adding the header
X-Krakend-Completed: false (some backends succeeded, others don’t) and also by adding the detailed errors feature.
If what you need is returning the content of a backend service as is, then the no-op encoding will proxy the client call to the backend service without any manipulation. When the backend produces the response, it’s passed back to the client, preserving its form: body, headers, status codes, and such.
An exception to this behavior is
30x responses, which will be followed by the gateway even with
no-op encoding. If your backend returns a
301 the client won’t follow it, but the gateway.
Default status codes can be overridden per endpoint, following different implementations.
custom_error, with any status code of your choice.
custom_error will end the pipe execution. If you just want to alter the status code, you can (in a no-op pipe) use the
statusCode dynamic helper on the response.
The documentation is only a piece of the help you can get! Whether you are looking for Open Source or Enterprise support, see more support channels that can help you.