exit-transformer - Apisix

<head> <link rel="canonical" href="https://docs.api7.ai/hub/exit-transformer" /> </head>

Description

The exit-transformer Plugin intercepts responses generated by APISIX itself — such as authentication failures, rate-limit rejections, or upstream errors — and transforms them using user-defined Lua functions before sending to the client.

The Plugin registers callbacks that are invoked when core.response.exit() is called, receiving the response (status_code, body, headers) as arguments and returning the (possibly modified) values. Multiple functions can be chained, and each function's output becomes the next function's input.

:::note

This Plugin only transforms responses generated by APISIX's own core.response.exit() mechanism. It does not transform responses that originate from upstream services.

:::

Attributes

Name	Type	Required	Default	Valid values	Description
functions	array[string]	True			An array of Lua function source strings. Each string must be a complete Lua chunk that returns a function. The function receives `(status_code, body, headers)` and must return `status_code, body, headers` (modified or unchanged). If a function throws an error, it is logged and the original values are passed to the next function.

Each Lua function string must be a chunk that evaluates to a function with the following signature:

lua

return (function(code, body, header)
    -- modify code, body, or header as needed
    return code, body, header
end)(...)

Examples

The examples below demonstrate how you can configure exit-transformer in different scenarios.

:::note

bash

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

:::

Remap Status Codes

The following example demonstrates how to remap a 404 Not Found response to 405 Method Not Allowed.

shell

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "exit-transformer-route",
    "uri": "/anything",
    "plugins": {
      "key-auth": {},
      "exit-transformer": {
        "functions": [
          "return (function(code, body, header) if code == 401 then return 403, body, header end return code, body, header end)(...)"
        ]
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {"httpbin.org:80": 1}
    }
  }'

Send a request without an API key:

shell

curl -i "http://127.0.0.1:9080/anything"

You should receive a 403 Forbidden response instead of the default 401 Unauthorized.

Normalize Error Response Format

The following example demonstrates how to rewrite any error response body to a consistent JSON format and add a custom header.

shell

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "exit-transformer-route",
    "uri": "/anything",
    "plugins": {
      "key-auth": {},
      "exit-transformer": {
        "functions": [
          "return (function(code, body, header) if code and code >= 400 then header = header or {} header[\"X-Error-Code\"] = tostring(code) body = {error = true, status = code, message = (type(body) == \"table\" and body.message) or \"request failed\"} end return code, body, header end)(...)"
        ]
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {"httpbin.org:80": 1}
    }
  }'

Send a request without an API key:

shell

curl -i "http://127.0.0.1:9080/anything"

You should receive a 401 response with a normalized JSON body and the X-Error-Code: 401 header:

json

{"error":true,"status":401,"message":"Missing API key in request"}