Alchemy 429 "Monthly capacity limit exceeded" causes ~4 minute delay before SERVER_ERROR (no timeout control?)

[TheGreatHB]

Ethers Version

6.15.0

Search Terms

No response

Describe the Problem

When my Alchemy project exceeds its monthly capacity limit, the RPC returns a 429 error immediately, but ethers keeps retrying for about 3–4 minutes before throwing. This happens with both AlchemyProvider and JsonRpcProvider.

With AlchemyProvider, it eventually throws a SERVER_ERROR after the long delay.

With JsonRpcProvider, the behavior is the same, but the final error also includes:

JsonRpcProvider failed to detect network and cannot start up; retry in 1s
(perhaps the URL is wrong or the node is not started)

This message is misleading because the URL and node are valid — the failure is purely due to Alchemy’s hard 429 “monthly capacity limit exceeded” response. Ideally, this unrecoverable 429 should fail fast or be configurable via timeout or retry settings, rather than retrying for several minutes.

I saw #4827, which was fixed in 6.13.4. I’m on 6.15.0, so that fix is included, but this seems to be a different case: the RPC endpoint is reachable and responds with a valid JSON-RPC 429 “Monthly capacity limit exceeded”, and after 3–4 minutes of retries JsonRpcProvider still ends up throwing the same “failed to detect network” message.

Code Snippet

// Case 1
  const provider1 = new ethers.AlchemyProvider("mainnet", "<api-key>");

  // Case 2 (same project / same endpoint)
  const provider2 = new ethers.JsonRpcProvider(
    "https://eth-mainnet.g.alchemy.com/v2/<api-key>"
  );

  const block = await provider.getBlock("latest");

Contract ABI

Errors

[Running] node "/home/hb/projects/ethers_test/test.js"
Error: exceeded maximum retry limit (request={  }, response={  }, error=null, info={ "requestUrl": "https://eth-mainnet.alchemyapi.io/v2/<api-key>", "responseBody": "{\"jsonrpc\":\"2.0\",\"id\":1,\"error\":{\"code\":429,\"message\":\"Monthly capacity limit exceeded. Visit https://dashboard.alchemy.com/settings/billing to upgrade your scaling policy for continued service.\"}}", "responseStatus": "599 CLIENT ESCALATED SERVER ERROR (429 Too Many Requests; exceeded maximum retry limit)" }, code=SERVER_ERROR, version=6.15.0)
    at makeError (/home/hb/projects/ethers_test/node_modules/ethers/lib.commonjs/utils/errors.js:137:21)
    at assert (/home/hb/projects/ethers_test/node_modules/ethers/lib.commonjs/utils/errors.js:157:15)
    at FetchResponse.assertOk (/home/hb/projects/ethers_test/node_modules/ethers/lib.commonjs/utils/fetch.js:839:32)
    at AlchemyProvider._send (/home/hb/projects/ethers_test/node_modules/ethers/lib.commonjs/providers/provider-jsonrpc.js:917:18)
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
    at async /home/hb/projects/ethers_test/node_modules/ethers/lib.commonjs/providers/provider-jsonrpc.js:281:40 {
  code: 'SERVER_ERROR',
  request: FetchRequest {},
  response: FetchResponse {},
  error: undefined,
  info: {
    requestUrl: 'https://eth-mainnet.alchemyapi.io/v2/<api-key>',
    responseBody: '{"jsonrpc":"2.0","id":1,"error":{"code":429,"message":"Monthly capacity limit exceeded. Visit https://dashboard.alchemy.com/settings/billing to upgrade your scaling policy for continued service."}}',
    responseStatus: '599 CLIENT ESCALATED SERVER ERROR (429 Too Many Requests; exceeded maximum retry limit)'
  },
  shortMessage: 'exceeded maximum retry limit'
}

[Done] exited with code=0 in 261.337 seconds

Environment

node.js (v12 or newer)

Environment (Other)

No response