Description

When an AI proxy request times out reaching the upstream LLM, the client receives 500 Internal Server Error instead of 504 Gateway Timeout.

apisix/plugins/ai-transport/http.lua maps errors to 504 only when the error string contains the contiguous substring timeout:

function _M.handle_error(err)
    if core.string.find(err, "timeout") then
        return 504
    end
    return 500
end

core.string.find is a plain-text search, and an OS connect timeout surfaces as Operation timed out / Connection timed out, which contains timed out (with a space), not the contiguous timeout. So it falls through to the default 500.

Timeout error taxonomy

handle_error receives its error from lua-resty-http over OpenResty cosockets. lua-resty-http propagates the raw cosocket error unchanged (return nil, err in every connect/send/receive/body-reader path), so the only timeout spellings that can reach handle_error are produced by the cosocket layer and the nginx resolver:

The complete timeout set collapses to exactly two substrings: timeout (cosocket timer) and timed out (errno / resolver). Matching both is necessary (the bare timeout case has no space; the … timed out cases have no contiguous timeout) and sufficient. Non-timeout errors (connection refused, connection reset by peer, closed) keep returning 500.

Fix

Match timed out in addition to timeout:

function _M.handle_error(err)
    if core.string.find(err, "timeout") or core.string.find(err, "timed out") then
        return 504
    end
    return 500
end

handle_error is the single status mapper behind all AI upstream failure paths (ai-proxy request/metric, ai-providers sidecar request and streaming read), so all of them now return 504 on timeout.

Tests

Added two cases to t/plugin/ai-transport-http.t:

• a regression test that mocks connect returning Operation timed out and asserts the mapped status is 504;
• a matrix over one representative per timeout class plus non-timeout controls.

Both fail before the change (the … timed out cases return 500) and pass after.

Checklist

• I have explained the need for this PR and the problem it solves
• I have explained the changes or the new features added to this PR
• I have added tests corresponding to this change
• I have updated the documentation to reflect this change (N/A — internal error-code mapping, no documented behavior change)
• I have verified that this change is backward compatible (timeouts previously returned 500; they now return the more accurate 504)