[bliuchak]

Closes #593

What

Exports the custom 590–599 status codes from the package entry point as UPSTREAM_ERROR_STATUS_CODE, plus the UpstreamErrorStatusCode type for their values:

import { UPSTREAM_ERROR_STATUS_CODE } from 'proxy-chain';

if (response.status === UPSTREAM_ERROR_STATUS_CODE.AUTH_FAILED) {
    // Incorrect upstream proxy credentials
}

Why

The codes are already a documented public contract in the README, so consumers end up hard-coding them. Exporting the constant lets them reference the codes by name.

How

• Renamed the internal badGatewayStatusCodes to UPSTREAM_ERROR_STATUS_CODE, following the constant naming in docs/agents/typescript.md.
• Only 590–599 are exported. The 504 timeout code stays internal, because a target can return its own 504, which the proxy passes through, so clients could not tell the two apart.
• Wrapped the object in Object.freeze, so a consumer can't change the codes the server itself responds with.
• Only this constant and its type are exported. The other helpers in statuses.ts stay internal.
• The README maps each key to its code. The STATUS_CODES reason phrases are now registered by key instead of repeating the numbers.

Risks

This only adds to the public API. Once released, renaming the constant or its keys would be a breaking change.

Testing

Type-check, lint, build and unit tests pass. The e2e suite fails the same 55 puppeteer and SOCKS tests with and without this change, in an environment without a browser or SOCKS upstream, and has no new failures.

https://claude.ai/code/session_01UdrrEDhY1FTbje75nFktTS

---

Generated by Claude Code

[daniil-poletaev]

Looks good!

Just 1 thing:
new UpstreamErrorStatusCode type doesn't include 504, but the server still returns 504 when an upstream proxy times out. Is it intended?

[bliuchak]

Yes, leaving 504 out is intentional. The proxy still returns 504 when an upstream proxy times out, but only internally, through UPSTREAM_TIMEOUT_STATUS_CODE in src/statuses.ts.

It isn't exported because a target server can send its own 504, and the proxy passes that through unchanged. A client that sees 504 therefore can't tell an upstream proxy timeout from the target's own gateway timeout. Treating it as an upstream error would be wrong some of the time.

UPSTREAM_ERROR_STATUS_CODE and UpstreamErrorStatusCode only cover 590–599. The proxy is the only thing that sends those codes, so a client can rely on them. 504 keeps its standard HTTP meaning.

---

Generated by Claude Code