DigitalOcean API rate‑limit headers and connection‑pool exhaustion behavior

Direct answer

When X-RateLimit-Remaining reaches zero, the next request returns 429 Too Many Requests with a Retry-After header (seconds) and an X-RateLimit-Reset timestamp (Unix epoch). The recommended back‑off for any client (SDK or custom) is:

1. Read Retry-After (if present) and compute resetWait = X-RateLimit-Reset - now().
2. Wait max(Retry-After, resetWait) + jitter, where jitter is a random value in 0–250 ms.
3. If either header is missing, fall back to exponential back‑off starting at 1 s, doubling each retry, capped at 60 s.

The platform does not expose per‑endpoint limits; all endpoints share a single global bucket per OAuth token or API key (default 5 000 requests/hour).

To prevent connection‑pool saturation across multiple pools, gate every outbound request with a shared token‑bucket keyed by the credential. Acquire a permit before borrowing a connection from any pool, and release the permit after the response (including 429). This ensures the total concurrent requests never exceed the global limit.

Confirmed facts (from DigitalOcean documentation and SDK behaviour)

• Headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset are present on every response.
• A 429 response always includes Retry-After (seconds) and repeats X-RateLimit-Reset.
• Official SDKs (Go, Ruby, Python, Node, Terraform provider) implement automatic retries with exponential back‑off and jitter, honouring both Retry-After and X-RateLimit-Reset.
• No per‑endpoint limit headers or APIs exist; the control plane only enforces the global bucket.
• DigitalOcean may change limit values or windows without notice; treat X-RateLimit-Limit as advisory and always obey the dynamic headers.

Likely explanation / practical guidance

Custom HTTP client implementation

async function doRequest(req) {
  await rateLimiter.acquire();          // shared token bucket
  try {
    const resp = await httpClient.request(req);
    updateRateLimiterFromHeaders(resp.headers);
    return resp;
  } catch (err) {
    if (err.status === 429) {
      const wait = computeBackoff(err.headers);
      await sleep(wait);
      return doRequest(req);            // retry once after back‑off
    }
    throw err;
  } finally {
    rateLimiter.release();
  }
}

function computeBackoff(headers) {
  const retryAfter = headers['retry-after'] ? parseInt(headers['retry-after'], 10) * 1000 : 0;
  const reset = headers['x-ratelimit-reset'] ? (parseInt(headers['x-ratelimit-reset'], 10) * 1000 - Date.now()) : 0;
  const base = Math.max(retryAfter, reset, 0);
  const jitter = Math.random() * 250;
  return base + jitter;
}

Coordinating multiple connection pools

• Use a single in‑memory token bucket (or Redis‑backed for distributed processes) per credential.
• Configure each pool’s maximum size to a value comfortably below the hourly limit (e.g., 50–100 connections) so the bucket, not the pool, is the bottleneck.
• Acquire the bucket permit before calling pool.acquire() (or equivalent) to avoid queuing connections that will immediately hit a 429.

Verification steps you can run today

1. Send a burst of requests (e.g., 6 000 in a minute) until you receive a 429. Inspect X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After.
2. Enable SDK debug logging (e.g., GOOGLE_API_GO_DEBUG=1 for the Go SDK) and confirm the back‑off intervals match the header‑driven formula.
3. Load‑test your custom client against a mock server that reproduces the DigitalOcean headers; verify that no connection‑pool exhaustion occurs when the shared bucket is used.
4. Check the current DigitalOcean API docs (developers.digitalocean.com) for any announced limit changes.

One diagnostic detail that would change the recommendation

If your client’s system clock is not synchronized (NTP offset > 1 s), the computed resetWait can become negative, causing immediate retries. Confirm clock sync before relying on X-RateLimit-Reset.

Cautions

• Retry-After may be absent on non‑429 errors; do not assume its presence for other status codes.
• Connection‑pool libraries (HikariCP, Apache HttpClient, Go http.DefaultTransport, etc.) have independent queue limits; the shared bucket must gate before the pool acquire call.
• Using multiple API tokens to circumvent the global limit violates DigitalOcean Terms of Service and can lead to account suspension.