Rate limit handling on endpoints

[interstella-5555]

Currently rate limited requests return these headers from coingecko api

< x-ratelimit-limit: 30
< x-ratelimit-remaining: 0
< x-ratelimit-reset: 2025-07-25 14:54:00 +0000

but sdk only supports handling retry-after-ms and retry-after

    // Note the `retry-after-ms` header may not be standard, but is a good idea and we'd like proactive support for it.
    const retryAfterMillisHeader = responseHeaders?.get('retry-after-ms');
    if (retryAfterMillisHeader) {
      const timeoutMs = parseFloat(retryAfterMillisHeader);
      if (!Number.isNaN(timeoutMs)) {
        timeoutMillis = timeoutMs;
      }
    }

    // About the Retry-After header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
    const retryAfterHeader = responseHeaders?.get('retry-after');
    if (retryAfterHeader && !timeoutMillis) {
      const timeoutSeconds = parseFloat(retryAfterHeader);
      if (!Number.isNaN(timeoutSeconds)) {
        timeoutMillis = timeoutSeconds * 1000;
      } else {
        timeoutMillis = Date.parse(retryAfterHeader) - Date.now();
      }
    }

Solutions

1. ping method should return 'retry-after' header
2. coingecko api could calculate 'retry-after-ms' based on delta between now and x-ratelimit-reset and include 'retry-after-ms' header
3. sdk could include handling 'x-ratelimit-reset' header (not sure if that's easy with stainless 🤷 )

[interstella-5555]

Oh I think I am mistaken on this one. It does seem like those x-ratelimit-* headers are only on ping method (which doesn't work with demo key on sdk fwiw so I tested curl). I tested sdk with coins.markets and it returned retry-after correctly.

My /ping 429 response headers fwiw

< HTTP/2 429 
< date: Fri, 25 Jul 2025 18:42:21 GMT
< content-length: 10
< server: cloudflare
< x-ratelimit-limit: 30
< x-ratelimit-remaining: 0
< x-ratelimit-reset: 2025-07-25 18:43:00 +0000
< vary: Origin, accept-encoding
< content-security-policy-report-only: script-src https://accounts.google.com/gsi/client; frame-src https://accounts.google.com/gsi/; connect-src https://accounts.google.com/gsi/;
< strict-transport-security: max-age=15724800; includeSubdomains
< cf-cache-status: BYPASS
< cf-ray: 964dcbf3c9810206-WAW
< alt-svc: h3=":443"; ma=86400

[interstella-5555]

small update on my end, I tested this today from sdk on pro api key on coins tickers endpoint and I got these headers in response

  "cf-cache-status": "MISS",
  "cf-ray": "965dcc5d9fd3ecba-WAW",
  "connection": "keep-alive",
  "content-length": "10",
  "content-security-policy-report-only": "script-src https://accounts.google.com/gsi/client; frame-src https://accounts.google.com/gsi/; connect-src https://accounts.google.com/gsi/;",
  "date": "Sun, 27 Jul 2025 17:18:50 GMT",
  "server": "cloudflare",
  "strict-transport-security": "max-age=15724800; includeSubdomains",
  "vary": "Origin, Accept-Encoding",
  "x-ratelimit-limit": "1000",
  "x-ratelimit-remaining": "0",
  "x-ratelimit-reset": "2025-07-27 17:19:00 +0000"

so these do not include retry-after after all, I am 100% confused at this point but maybe it does make more sense to one of your devs working on the api, would appreciate looking into that

[cg-eesuhn]

Hi @kwypchlo, thanks for highlighting this, and apologize for the late response.

One thing to note is that we don’t currently support retry-after (or similar headers) across both our API and SDK. We’ve logged this as a feature request internally, but there’s no confirmed ETA at the moment.