Rate Limiting

Zavu implements rate limiting to ensure fair usage and protect the platform from abuse. All API requests to /v1/* endpoints are subject to rate limiting.

Rate Limit Tiers

Your rate limit depends on your project’s verification status:

Tier	Limit	Eligibility
Default	600 requests/min	All new projects
Compliance Verified	1,200 requests/min	Projects with verified business compliance
10DLC Verified	2,400 requests/min	Projects with approved 10DLC campaign

Rate limits are applied per project. If you have multiple projects, each has its own independent rate limit.

How to Increase Your Limit

Complete Compliance Verification

Submit your business information and use case in the dashboard under Settings > Compliance. Once verified, your limit automatically increases to 1,200 requests/min (2x).

If you’re sending SMS to US recipients, register your brand and campaign for 10DLC compliance. Approved campaigns receive 2,400 requests/min (4x).

Verification is automatic - once approved, your rate limit increases immediately with no code changes needed.

Rate Limit Headers

Every API response includes headers to help you track your rate limit usage:

Header	Description	Example
`X-RateLimit-Limit`	Maximum requests per minute	`600`
`X-RateLimit-Remaining`	Requests remaining in current window	`542`
`X-RateLimit-Reset`	Unix timestamp (ms) when window resets	`1701234600000`
`Retry-After`	Seconds until reset (only on 429)	`45`

Checking Rate Limits with the SDK

Use .withResponse() to access the rate limit headers:

import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev({
  apiKey: process.env['ZAVUDEV_API_KEY'],
});

// Use .withResponse() to get the full HTTP response
const { response, result } = await zavu.messages.send.withResponse({
  to: "+14155551234",
  text: "Hello from Zavu!",
});

// Access rate limit headers
const limit = response.headers.get("X-RateLimit-Limit");
const remaining = response.headers.get("X-RateLimit-Remaining");
const reset = response.headers.get("X-RateLimit-Reset");

console.log(`Rate limit: ${remaining}/${limit} requests remaining`);
console.log(`Window resets at: ${new Date(Number(reset)).toISOString()}`);

// Access the message result as usual
console.log("Message ID:", result.message.id);

import os
from zavudev import Zavudev

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),
)

response = zavu.messages.send.with_raw_response(
    to="+14155551234",
    text="Hello from Zavu!"
)

# Access rate limit headers
limit = response.headers.get("X-RateLimit-Limit")
remaining = response.headers.get("X-RateLimit-Remaining")
reset = response.headers.get("X-RateLimit-Reset")

print(f"Rate limit: {remaining}/{limit} requests remaining")

# Access the parsed result
result = response.parse()
print(f"Message ID: {result.message.id}")

require 'zavudev'

zavu = Zavudev::Client.new(
  api_key: ENV['ZAVUDEV_API_KEY']
)

response = zavu.messages.send_with_response(
  to: "+14155551234",
  text: "Hello from Zavu!"
)

# Access rate limit headers
limit = response.headers["X-RateLimit-Limit"]
remaining = response.headers["X-RateLimit-Remaining"]
reset = response.headers["X-RateLimit-Reset"]

puts "Rate limit: #{remaining}/#{limit} requests remaining"

# Access the message result
puts "Message ID: #{response.data.message.id}"

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/zavudev/sdk-go"
)

func main() {
    client := zavudev.NewClient(
        zavudev.WithAPIKey(os.Getenv("ZAVUDEV_API_KEY")),
    )

    result, err := client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
        To:   zavudev.String("+14155551234"),
        Text: zavudev.String("Hello from Zavu!"),
    })

    // Access rate limit headers from the response
    // Headers are available via the raw HTTP response
    fmt.Println("Message ID:", result.Message.ID)
}

$zavu = new Zavudev\Client(['apiKey' => getenv('ZAVUDEV_API_KEY')]);

$response = $zavu->messages->sendWithResponse([
    'to' => '+14155551234',
    'text' => 'Hello from Zavu!',
]);

// Access rate limit headers
$limit = $response->headers['X-RateLimit-Limit'];
$remaining = $response->headers['X-RateLimit-Remaining'];
$reset = $response->headers['X-RateLimit-Reset'];

echo "Rate limit: {$remaining}/{$limit} requests remaining\n";
echo "Message ID: " . $response->data->message->id . "\n";

curl -i -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155551234", "text": "Hello!"}'

# Response headers will include:
# X-RateLimit-Limit: 600
# X-RateLimit-Remaining: 599
# X-RateLimit-Reset: 1701234600000

Rate Limit Exceeded (429)

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

{
  "code": "rate_limited",
  "message": "Rate limit exceeded. Retry after 2024-01-15T12:30:00.000Z",
  "details": {
    "retryAfter": 1705322400000
  }
}

Handling Rate Limits

Here’s how to properly handle rate limiting in your application:

import { Zavu } from "@zavudev/sdk";
import * as errors from "@zavudev/sdk/models/errors";

const zavu = new Zavu({
  bearerAuth: process.env.ZAVUDEV_API_KEY,
});

async function sendWithRateLimitHandling(to: string, text: string) {
  try {
    const { response, result } = await zavu.messages.send.withResponse({
      to, text,
    });

    // Check remaining quota
    const remaining = Number(response.headers.get("X-RateLimit-Remaining"));
    if (remaining < 10) {
      console.warn(`Low rate limit: ${remaining} requests remaining`);
    }

    return result;
  } catch (error) {
    if (error instanceof errors.SDKError && error.statusCode === 429) {
      // Get retry time from error or headers
      const retryAfter = error.body?.details?.retryAfter;
      const waitMs = retryAfter ? retryAfter - Date.now() : 60000;

      console.log(`Rate limited. Waiting ${waitMs}ms before retry...`);
      await new Promise(resolve => setTimeout(resolve, waitMs));

      // Retry the request
      return sendWithRateLimitHandling(to, text);
    }
    throw error;
  }
}

import os
import time
from zavu_sdk import Zavu
from zavu_sdk.models import errors

def send_with_rate_limit_handling(zavu, to: str, text: str):
    try:
        response = zavu.messages.send.with_raw_response(to=to, text=text)

        # Check remaining quota
        remaining = int(response.headers.get("X-RateLimit-Remaining", 0))
        if remaining < 10:
            print(f"Warning: Low rate limit - {remaining} requests remaining")

        return response.parse()
    except errors.SDKError as e:
        if e.status_code == 429:
            retry_after = e.body.get("details", {}).get("retryAfter")
            wait_seconds = (retry_after - time.time() * 1000) / 1000 if retry_after else 60

            print(f"Rate limited. Waiting {wait_seconds:.1f}s before retry...")
            time.sleep(max(wait_seconds, 0))

            return send_with_rate_limit_handling(zavu, to, text)
        raise

require 'zavudev'

def send_with_rate_limit_handling(zavu, to:, text:)
  response = zavu.messages.send_with_response(to: to, text: text)

  remaining = response.headers["X-RateLimit-Remaining"].to_i
  if remaining < 10
    puts "Warning: Low rate limit - #{remaining} requests remaining"
  end

  response.data
rescue Zavudev::RateLimitError => e
  retry_after = e.retry_after || 60
  puts "Rate limited. Waiting #{retry_after}s before retry..."
  sleep(retry_after)
  send_with_rate_limit_handling(zavu, to: to, text: text)
end

package main

import (
    "context"
    "fmt"
    "time"

    "github.com/zavudev/sdk-go"
)

func sendWithRateLimitHandling(client *zavudev.Client, to, text string) (*zavudev.MessageResponse, error) {
    result, err := client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
        To:   zavudev.String(to),
        Text: zavudev.String(text),
    })

    if err != nil {
        if rateLimitErr, ok := err.(*zavudev.RateLimitError); ok {
            retryAfter := rateLimitErr.RetryAfter
            if retryAfter == 0 {
                retryAfter = 60 * time.Second
            }
            fmt.Printf("Rate limited. Waiting %v before retry...\n", retryAfter)
            time.Sleep(retryAfter)
            return sendWithRateLimitHandling(client, to, text)
        }
        return nil, err
    }

    return result, nil
}

function sendWithRateLimitHandling($client, string $to, string $text) {
    try {
        $response = $client->messages->sendWithResponse([
            'to' => $to,
            'text' => $text,
        ]);

        $remaining = (int) $response->headers['X-RateLimit-Remaining'];
        if ($remaining < 10) {
            echo "Warning: Low rate limit - {$remaining} requests remaining\n";
        }

        return $response->data;
    } catch (\Zavudev\Exceptions\RateLimitException $e) {
        $retryAfter = $e->retryAfter ?? 60;
        echo "Rate limited. Waiting {$retryAfter}s before retry...\n";
        sleep($retryAfter);
        return sendWithRateLimitHandling($client, $to, $text);
    }
}

How It Works

Zavu uses a fixed window algorithm for rate limiting:

Window: 12:00:00 - 12:00:59
├── Request 1: OK (remaining: 599)
├── Request 2: OK (remaining: 598)
├── ...
├── Request 600: OK (remaining: 0)
└── Request 601: 429 Rate Limited

Window: 12:01:00 - 12:01:59
└── Request 1: OK (remaining: 599) ← Counter resets!

The counter resets at the start of each minute (e.g., 12:00:00, 12:01:00, 12:02:00).

Best Practices

Monitor Headers

Always check X-RateLimit-Remaining to avoid hitting limits unexpectedly.

Implement Backoff

Use the Retry-After header or retryAfter field to wait the correct amount of time.

Use Broadcasts

For bulk sending, use our Broadcasts API instead of individual requests.

Use Idempotency Keys

Include idempotencyKey in requests to safely retry without duplicates.

Bulk Sending Example

For sending many messages, implement a simple rate limiter:

import Zavudev from '@zavudev/sdk';

const zavu = new Zavudev({
  apiKey: process.env['ZAVUDEV_API_KEY'],
});

async function sendBulkMessages(messages: { to: string; text: string }[]) {
  const results = [];
  let remaining = 600;

  for (const msg of messages) {
    // If running low, wait for next window
    if (remaining < 10) {
      console.log("Approaching rate limit, waiting for next window...");
      await new Promise(resolve => setTimeout(resolve, 60000));
      remaining = 600;
    }

    const { response, result } = await zavu.messages.send.withResponse(msg);

    remaining = Number(response.headers.get("X-RateLimit-Remaining"));
    results.push(result);
  }

  return results;
}

For sending to more than 100 recipients, we strongly recommend using the Broadcasts API instead. Broadcasts handle rate limiting, retries, and progress tracking automatically.

Summary

Tier	Limit	How to Get
Default	600/min	Automatic for all projects
Compliance Verified	1,200/min	Complete business verification
10DLC Verified	2,400/min	Register 10DLC brand & campaign

Getting Started

Build agents

Send & receive

Operate

Developer tools

Integrations

Rate Limiting

Rate Limiting

Rate Limit Tiers

How to Increase Your Limit

Rate Limit Headers

Checking Rate Limits with the SDK

Rate Limit Exceeded (429)

Handling Rate Limits

How It Works

Best Practices

Monitor Headers

Implement Backoff

Use Broadcasts

Use Idempotency Keys

Bulk Sending Example

Summary

Next Steps

Compliance Verification

Broadcasts API

​Rate Limiting

​Rate Limit Tiers

​How to Increase Your Limit

​Rate Limit Headers

​Checking Rate Limits with the SDK

​Rate Limit Exceeded (429)

​Handling Rate Limits

​How It Works

​Best Practices

Monitor Headers

Implement Backoff

Use Broadcasts

Use Idempotency Keys

​Bulk Sending Example

​Summary

​Next Steps

Compliance Verification

Broadcasts API

Rate Limiting

Rate Limit Tiers

How to Increase Your Limit

Rate Limit Headers

Checking Rate Limits with the SDK

Rate Limit Exceeded (429)

Handling Rate Limits

How It Works

Best Practices

Bulk Sending Example

Summary

Next Steps