> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dashlink.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Working within rate limits

> Structuring a high-volume integration so it never sees a 429.

[Rate limits](https://docs.dashlink.ai/api-reference/concepts/rate-limits.md) lists the per-plan numbers and the headers. This is about building something that stays under them by design, instead of backing off after the fact.

## Do less work first

Before tuning concurrency, check you are not making requests you did not need:

> [accordion] Bulk endpoints instead of loops
>
> `bulk_edit` applies one change across many links in a single request. A thousand sequential `update_shortlink` calls is a thousand requests against a budget that a handful of bulk calls would barely touch.

> [accordion] Batch your dashboard metrics
>
> `get_org_metrics_batch` takes several dimensions at once. Four widgets, one request.

> [accordion] Raise per\_page
>
> `per_page=100` walks 10,000 records in 100 requests. The default of 10 makes it 1,000.

> [accordion] Cache what cannot change
>
> Yesterday's analytics are final. Domain lists and UTM templates change rarely. Neither needs re-fetching on every page load.

## Spend the budget deliberately

The budget belongs to your organization and every key draws on the same one, so a key is a credential and a permission scope — not a throughput allocation. A nightly export running flat out will starve the requests serving your product's UI, and moving it to its own key does not change that.

Decide what the interactive path needs, then keep batch work inside what is left: run exports off-peak, cap their concurrency, and have them back off first when the two compete.

Give each integration its own key regardless, [scoped to what it needs](https://docs.dashlink.ai/guides/api-keys.md). That is what lets you revoke one without an outage everywhere else, and tell from the access pattern which system is spending the budget.

## Pace against the headers

Every response tells you where you stand. Use it rather than sleeping a fixed amount:

```bash cURL theme={null}
# Ease off while the window is still open instead of waiting for a 429.
headers=$(mktemp)
curl -sS -D "$headers" -o /dev/null \
  -H "X-API-Key: $DASHLINK_API_KEY" \
  "https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?per_page=1"
limit=$(awk 'tolower($1)=="x-ratelimit-limit:" {print $2}' "$headers" | tr -d '\r')
remaining=$(awk 'tolower($1)=="x-ratelimit-remaining:" {print $2}' "$headers" | tr -d '\r')
reset=$(awk 'tolower($1)=="x-ratelimit-reset:" {print $2}' "$headers" | tr -d '\r')
divisor=${remaining:-0}
[ "$divisor" -lt 1 ] && divisor=1
if [ "${limit:--1}" -ge 0 ] && [ "${remaining:-0}" -lt $((limit / 10)) ]; then
  sleep $(( ${reset:-0} / divisor ))
fi
```

```javascript Node.js theme={null}
// Spreads remaining requests over the remaining window once the budget
// runs low, so a burst decays into a trickle instead of a 429.
class Pacer {
  constructor(floor = 0.1) {
    this.floor = floor;
  }

  async observe(response) {
    const limit = Number(response.headers.get("X-RateLimit-Limit") ?? -1);
    if (limit < 0) return;

    const remaining = Number(
      response.headers.get("X-RateLimit-Remaining") ?? limit
    );
    const reset = Number(response.headers.get("X-RateLimit-Reset") ?? 60);

    if (remaining <= 0) {
      await sleep(reset);
    } else if (remaining < limit * this.floor) {
      await sleep(reset / remaining);
    }
  }
}

const sleep = (seconds) =>
  new Promise((resolve) => setTimeout(resolve, seconds * 1000));
```

```python Python theme={null}
import time

class Pacer:
    """Spreads remaining requests over the remaining window once the
    budget runs low, so a burst decays into a trickle instead of a 429."""

    def __init__(self, floor=0.1):
        self.floor = floor

    def observe(self, response):
        limit = int(response.headers.get("X-RateLimit-Limit", -1))
        if limit < 0:
            return

        remaining = int(response.headers.get("X-RateLimit-Remaining", limit))
        reset = int(response.headers.get("X-RateLimit-Reset", 60))

        if remaining <= 0:
            time.sleep(reset)
        elif remaining < limit * self.floor:
            time.sleep(reset / remaining)
```

```go Go theme={null}
// Pacer spreads remaining requests over the remaining window once the
// budget runs low, so a burst decays into a trickle instead of a 429.
type Pacer struct {
	Floor float64 // fraction of the limit below which pacing kicks in
}

func (p *Pacer) Observe(resp *http.Response) {
	limit, err := strconv.Atoi(resp.Header.Get("X-RateLimit-Limit"))
	if err != nil {
		return
	}

	remaining := limit
	if v, err := strconv.Atoi(resp.Header.Get("X-RateLimit-Remaining")); err == nil {
		remaining = v
	}

	reset := 60
	if v, err := strconv.Atoi(resp.Header.Get("X-RateLimit-Reset")); err == nil {
		reset = v
	}

	switch {
	case remaining <= 0:
		time.Sleep(time.Duration(reset) * time.Second)
	case float64(remaining) < float64(limit)*p.Floor:
		time.Sleep(time.Duration(float64(reset)/float64(remaining)) * time.Second)
	}
}
```

```ruby Ruby theme={null}
# Spreads remaining requests over the remaining window once the budget
# runs low, so a burst decays into a trickle instead of a 429.
class Pacer
  def initialize(floor: 0.1)
    @floor = floor
  end

  def observe(response)
    limit = response["X-RateLimit-Limit"]&.to_i
    return if limit.nil?

    remaining = (response["X-RateLimit-Remaining"] || limit).to_i
    reset = (response["X-RateLimit-Reset"] || 60).to_i

    if remaining <= 0
      sleep reset
    elsif remaining < limit * @floor
      sleep reset.fdiv(remaining)
    end
  end
end
```

```php PHP theme={null}
<?php
// Spreads remaining requests over the remaining window once the budget
// runs low, so a burst decays into a trickle instead of a 429.
class Pacer
{
    public function __construct(private float $floor = 0.1)
    {
    }

    public function observe(array $headers): void
    {
        $limit = (int) ($headers['x-ratelimit-limit'] ?? -1);
        if ($limit < 0) {
            return;
        }

        $remaining = (int) ($headers['x-ratelimit-remaining'] ?? $limit);
        $reset = (int) ($headers['x-ratelimit-reset'] ?? 60);

        if ($remaining <= 0) {
            sleep($reset);
        } elseif ($remaining < $limit * $this->floor) {
            sleep((int) ceil($reset / $remaining));
        }
    }
}
```

## Concurrency that adapts

Fixed parallelism is either too slow or too fast. A semaphore that shrinks on a `429` finds the right level on its own:

```bash cURL theme={null}
# Shell stays sequential. On a 429, wait for Retry-After and try the same call again.
attempt=0
while [ "$attempt" -lt 5 ]; do
  headers=$(mktemp)
  code=$(curl -sS -D "$headers" -o /tmp/dashlink-body -w "%{http_code}" \
    -H "X-API-Key: $DASHLINK_API_KEY" \
    "https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?per_page=1")
  if [ "$code" != "429" ]; then
    cat /tmp/dashlink-body
    break
  fi
  wait=$(awk 'tolower($1)=="retry-after:" {print $2}' "$headers" | tr -d '\r')
  sleep "${wait:-$((2 ** attempt))}"
  attempt=$((attempt + 1))
done
```

```javascript Node.js theme={null}
class AdaptiveLimiter {
  constructor(initial = 8, minimum = 1, maximum = 32) {
    this.limit = initial;
    this.minimum = minimum;
    this.maximum = maximum;
    this.inFlight = 0;
    this.waiting = [];
  }

  async acquire() {
    if (this.inFlight >= this.limit) {
      await new Promise((resolve) => this.waiting.push(resolve));
    }
    this.inFlight++;
  }

  release() {
    this.inFlight--;
    this.waiting.shift()?.();
  }

  onSuccess() {
    // Grow slowly: one extra slot per full window without a 429.
    if (this.limit < this.maximum) {
      this.limit++;
      this.waiting.shift()?.();
    }
  }

  onRateLimited() {
    // Shrink hard. Being briefly too slow costs less than a queue of
    // requests that are all going to be rejected.
    this.limit = Math.max(this.minimum, Math.floor(this.limit / 2));
  }
}
```

```python Python theme={null}
import threading

class AdaptiveLimiter:
    def __init__(self, initial=8, minimum=1, maximum=32):
        self.limit = initial
        self.minimum, self.maximum = minimum, maximum
        self.lock = threading.Lock()
        self.semaphore = threading.Semaphore(initial)

    def on_success(self):
        with self.lock:
            # Grow slowly: one extra slot per full window without a 429.
            if self.limit < self.maximum:
                self.limit += 1
                self.semaphore.release()

    def on_rate_limited(self):
        with self.lock:
            # Shrink hard. Being briefly too slow costs less than a
            # queue of requests that are all going to be rejected.
            self.limit = max(self.minimum, self.limit // 2)
```

```go Go theme={null}
type AdaptiveLimiter struct {
	mu       sync.Mutex
	limit    int
	minimum  int
	maximum  int
	inFlight int
	free     *sync.Cond
}

func NewAdaptiveLimiter(initial, minimum, maximum int) *AdaptiveLimiter {
	l := &AdaptiveLimiter{limit: initial, minimum: minimum, maximum: maximum}
	l.free = sync.NewCond(&l.mu)
	return l
}

func (l *AdaptiveLimiter) Acquire() {
	l.mu.Lock()
	defer l.mu.Unlock()

	for l.inFlight >= l.limit {
		l.free.Wait()
	}
	l.inFlight++
}

func (l *AdaptiveLimiter) Release() {
	l.mu.Lock()
	defer l.mu.Unlock()

	l.inFlight--
	l.free.Signal()
}

func (l *AdaptiveLimiter) OnSuccess() {
	l.mu.Lock()
	defer l.mu.Unlock()

	// Grow slowly: one extra slot per full window without a 429.
	if l.limit < l.maximum {
		l.limit++
		l.free.Signal()
	}
}

func (l *AdaptiveLimiter) OnRateLimited() {
	l.mu.Lock()
	defer l.mu.Unlock()

	// Shrink hard. Being briefly too slow costs less than a queue of
	// requests that are all going to be rejected.
	if half := l.limit / 2; half > l.minimum {
		l.limit = half
	} else {
		l.limit = l.minimum
	}
}
```

```ruby Ruby theme={null}
class AdaptiveLimiter
  def initialize(initial: 8, minimum: 1, maximum: 32)
    @limit = initial
    @minimum = minimum
    @maximum = maximum
    @in_flight = 0
    @mutex = Mutex.new
    @free = ConditionVariable.new
  end

  def acquire
    @mutex.synchronize do
      @free.wait(@mutex) while @in_flight >= @limit
      @in_flight += 1
    end
  end

  def release
    @mutex.synchronize do
      @in_flight -= 1
      @free.signal
    end
  end

  def on_success
    @mutex.synchronize do
      # Grow slowly: one extra slot per full window without a 429.
      next unless @limit < @maximum

      @limit += 1
      @free.signal
    end
  end

  def on_rate_limited
    @mutex.synchronize do
      # Shrink hard. Being briefly too slow costs less than a queue of
      # requests that are all going to be rejected.
      @limit = [@minimum, @limit / 2].max
    end
  end
end
```

```php PHP theme={null}
<?php
// PHP request handlers are single-threaded, so the limiter tracks the
// concurrency of a curl_multi pool rather than of threads.
class AdaptiveLimiter
{
    private int $limit;

    public function __construct(
        int $initial = 8,
        private int $minimum = 1,
        private int $maximum = 32,
    ) {
        $this->limit = $initial;
    }

    public function limit(): int
    {
        return $this->limit;
    }

    public function onSuccess(): void
    {
        // Grow slowly: one extra slot per full window without a 429.
        if ($this->limit < $this->maximum) {
            $this->limit++;
        }
    }

    public function onRateLimited(): void
    {
        // Shrink hard. Being briefly too slow costs less than a queue of
        // requests that are all going to be rejected.
        $this->limit = max($this->minimum, intdiv($this->limit, 2));
    }
}
```

## Shape the load over time

**1. Queue rather than fan out**

A webhook that creates a link should enqueue the work. Traffic spikes then become queue depth instead of a wall of simultaneous requests.

**2. Stagger scheduled jobs**

Three jobs all starting at midnight contend for the same window. Offset them.

**3. Jitter your retries**

Everything that failed together retrying at exactly the same moment fails together again. Add randomness.

**4. Run big syncs off-peak**

A full reconciliation at 3am competes with nothing.

## Watch the right signal

Alert on `X-RateLimit-Remaining` trending toward zero, not on `429` counts. By the time you are counting rejections, users are already waiting. Log the header on a sample of responses and chart it — a slow decline over a week is a capacity conversation, a sudden cliff is a runaway loop.

> [!NOTE]
>
> Rate limits meter request volume. A `FEATURE_LIMIT_EXCEEDED` is a different thing entirely: your plan's allowance for a resource is exhausted, and no amount of waiting or pacing clears it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.