Rate Limits

The Ark API implements rate limiting to ensure fair usage and platform stability. This guide explains how rate limits work and how to handle them in your application.

Rate Limit Overview

Limit	Value
Requests per second	5

Rate limits are applied per API key using a sliding window algorithm.

Rate Limit Headers

Example Response Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 1705312800

Handling Rate Limits

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response:

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "suggestion": "Wait before retrying"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

The response includes a Retry-After header indicating how many seconds to wait.

SDK Automatic Retries

All Ark SDKs automatically handle rate limits with exponential backoff:

Python
Node.js
Ruby
Go

from ark import Ark

# SDKs automatically retry rate-limited requests
# Default: 2 retries with exponential backoff
client = Ark()

# Customize retry behavior
client = Ark(max_retries=5)  # More retries
client = Ark(max_retries=0)  # Disable retries

import Ark from 'ark';

// SDKs automatically retry rate-limited requests
// Default: 2 retries with exponential backoff
const client = new Ark();

// Customize retry behavior
const client = new Ark({ maxRetries: 5 });  // More retries
const client = new Ark({ maxRetries: 0 });  // Disable retries

require "ark_email"

# SDKs automatically retry rate-limited requests
# Default: 2 retries with exponential backoff
client = ArkEmail::Client.new

# Customize retry behavior
client = ArkEmail::Client.new(max_retries: 5)  # More retries
client = ArkEmail::Client.new(max_retries: 0)  # Disable retries

import (
    "github.com/ArkHQ-io/ark-go"
    "github.com/ArkHQ-io/ark-go/option"
)

// SDKs automatically retry rate-limited requests
// Default: 2 retries with exponential backoff
client := ark.NewClient()

// Customize retry behavior
client := ark.NewClient(option.WithMaxRetries(5))  // More retries
client := ark.NewClient(option.WithMaxRetries(0))  // Disable retries

Manual Rate Limit Handling

If you need custom rate limit handling:

Python
Node.js
Ruby
Go

import ark
import time

client = Ark(max_retries=0)  # Disable auto-retry

def send_with_rate_limit_handling(email_data, max_attempts=3):
    for attempt in range(max_attempts):
        try:
            return client.emails.send(**email_data)
        except ark.RateLimitError as e:
            if attempt == max_attempts - 1:
                raise
            # Get retry-after from headers if available
            wait_time = 1 * (2 ** attempt)  # Exponential backoff
            print(f"Rate limited, waiting {wait_time}s...")
            time.sleep(wait_time)

import Ark from 'ark';

const client = new Ark({ maxRetries: 0 }); // Disable auto-retry

async function sendWithRateLimitHandling(emailData: any, maxAttempts = 3) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await client.emails.send(emailData);
    } catch (error) {
      if (error instanceof Ark.RateLimitError && attempt < maxAttempts - 1) {
        const waitTime = 1000 * Math.pow(2, attempt); // Exponential backoff
        console.log(`Rate limited, waiting ${waitTime}ms...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      throw error;
    }
  }
}

require "ark_email"

client = ArkEmail::Client.new(max_retries: 0) # Disable auto-retry

def send_with_rate_limit_handling(email_data, max_attempts: 3)
  attempts = 0

  begin
    client.emails.send_(**email_data)
  rescue ArkEmail::Errors::RateLimitError => e
    attempts += 1
    raise if attempts >= max_attempts

    wait_time = 2 ** (attempts - 1)
    puts "Rate limited, waiting #{wait_time}s..."
    sleep(wait_time)
    retry
  end
end

import (
    "errors"
    "time"

    "github.com/ArkHQ-io/ark-go"
    "github.com/ArkHQ-io/ark-go/option"
)

client := ark.NewClient(option.WithMaxRetries(0)) // Disable auto-retry

func sendWithRateLimitHandling(ctx context.Context, params ark.EmailSendParams, maxAttempts int) (*ark.EmailResponse, error) {
    for attempt := 0; attempt < maxAttempts; attempt++ {
        email, err := client.Emails.Send(ctx, params)
        if err != nil {
            var arkErr *ark.Error
            if errors.As(err, &arkErr) && arkErr.StatusCode == 429 {
                if attempt < maxAttempts-1 {
                    waitTime := time.Duration(1<<attempt) * time.Second
                    fmt.Printf("Rate limited, waiting %v...\n", waitTime)
                    time.Sleep(waitTime)
                    continue
                }
            }
            return nil, err
        }
        return email, nil
    }
    return nil, errors.New("max attempts exceeded")
}

Best Practices

1. Use SDK Auto-Retries

The SDKs handle rate limits automatically. Just send your requests and they’ll retry with backoff:

Python
Node.js

# Just send emails - SDK handles rate limits automatically
for user in users:
    client.emails.send(
        from_="[email protected]",
        to=[user.email],
        subject="Update",
        html="<p>Hello!</p>"
    )

// Just send emails - SDK handles rate limits automatically
for (const user of users) {
  await client.emails.send({
    from: '[email protected]',
    to: [user.email],
    subject: 'Update',
    html: '<p>Hello!</p>',
  });
}

2. Use Batch Endpoints

Instead of making multiple individual requests, use the batch endpoint:

Python
Node.js
Ruby
Go

# Instead of this (100 requests)
for email in emails:
    client.emails.send(**email)

# Do this (1 request)
client.emails.send_batch(emails=emails)

// Instead of this (100 requests)
for (const email of emails) {
  await client.emails.send(email);
}

// Do this (1 request)
await client.emails.sendBatch({ emails });

# Instead of this (100 requests)
emails.each { |email| client.emails.send_(**email) }

# Do this (1 request)
client.emails.send_batch(emails: emails)

// Instead of this (100 requests)
for _, email := range emails {
    client.Emails.Send(ctx, email)
}

// Do this (1 request)
client.Emails.SendBatch(ctx, ark.EmailSendBatchParams{
    Emails: emails,
})

3. Implement Request Queuing

For applications that need to send many requests, queue them and process at a controlled rate:

Python
Node.js
Ruby
Go

import asyncio
from ark import Ark

client = Ark()

async def send_with_rate_limiting(emails, requests_per_second=4):
    interval = 1.0 / requests_per_second
    results = []

    for email in emails:
        result = client.emails.send(**email)
        results.append(result)
        await asyncio.sleep(interval)

    return results

# Usage - stay under 5 req/s limit
results = asyncio.run(send_with_rate_limiting(emails))

import Ark from 'ark';

const client = new Ark();

async function sendWithRateLimiting(emails: any[], requestsPerSecond = 4) {
  const interval = 1000 / requestsPerSecond;
  const results = [];

  for (const email of emails) {
    const result = await client.emails.send(email);
    results.push(result);
    await new Promise(resolve => setTimeout(resolve, interval));
  }

  return results;
}

// Usage - stay under 5 req/s limit
const results = await sendWithRateLimiting(emails);

require "ark_email"

client = ArkEmail::Client.new

def send_with_rate_limiting(emails, requests_per_second: 4)
  interval = 1.0 / requests_per_second
  results = []

  emails.each do |email|
    results << client.emails.send_(**email)
    sleep(interval)
  end

  results
end

# Usage - stay under 5 req/s limit
results = send_with_rate_limiting(emails)

import (
    "time"

    "github.com/ArkHQ-io/ark-go"
)

func sendWithRateLimiting(ctx context.Context, client *ark.Client, emails []ark.EmailSendParams, requestsPerSecond float64) ([]*ark.EmailResponse, error) {
    interval := time.Duration(float64(time.Second) / requestsPerSecond)
    results := make([]*ark.EmailResponse, 0, len(emails))

    for _, email := range emails {
        result, err := client.Emails.Send(ctx, email)
        if err != nil {
            return nil, err
        }
        results = append(results, result)
        time.Sleep(interval)
    }

    return results, nil
}

// Usage - stay under 5 req/s limit
results, _ := sendWithRateLimiting(ctx, client, emails, 4)

4. Use Exponential Backoff

The SDKs handle exponential backoff automatically. Configure the number of retries:

Python
Node.js
Ruby
Go

from ark import Ark

# Configure max retries - SDK uses exponential backoff automatically
client = Ark(max_retries=5)

# All requests will retry up to 5 times with exponential backoff
# for rate limits, timeouts, and server errors
email = client.emails.send(
    from_="[email protected]",
    to=["[email protected]"],
    subject="Hello",
    html="<p>Hello!</p>"
)

import Ark from 'ark';

// Configure max retries - SDK uses exponential backoff automatically
const client = new Ark({ maxRetries: 5 });

// All requests will retry up to 5 times with exponential backoff
// for rate limits, timeouts, and server errors
const email = await client.emails.send({
  from: '[email protected]',
  to: ['[email protected]'],
  subject: 'Hello',
  html: '<p>Hello!</p>',
});

require "ark_email"

# Configure max retries - SDK uses exponential backoff automatically
client = ArkEmail::Client.new(max_retries: 5)

# All requests will retry up to 5 times with exponential backoff
# for rate limits, timeouts, and server errors
email = client.emails.send_(
  from: "[email protected]",
  to: ["[email protected]"],
  subject: "Hello",
  html: "<p>Hello!</p>"
)

import (
    "github.com/ArkHQ-io/ark-go"
    "github.com/ArkHQ-io/ark-go/option"
)

// Configure max retries - SDK uses exponential backoff automatically
client := ark.NewClient(option.WithMaxRetries(5))

// All requests will retry up to 5 times with exponential backoff
// for rate limits, timeouts, and server errors
email, _ := client.Emails.Send(ctx, ark.EmailSendParams{
    From:    "[email protected]",
    To:      []string{"[email protected]"},
    Subject: "Hello",
    HTML:    ark.String("<p>Hello!</p>"),
})

Endpoint-Specific Limits

Email Sending

Endpoint	Limit	Value
`POST /emails`	To recipients	50 per email
`POST /emails`	CC recipients	50 per email
`POST /emails`	BCC recipients	50 per email
`POST /emails`	Subject length	998 characters
`POST /emails`	Tag length	1000 characters

Batch Emails

Endpoint	Limit	Value
`POST /emails/batch`	Emails per request	100
`POST /emails/batch`	Recipients per email	50
`POST /emails/batch`	Total recipients	1000 across all emails

Pagination

Endpoint	Default	Maximum
`GET /emails`	30 per page	100 per page
`GET /suppressions`	30 per page	100 per page

Suppressions

Endpoint	Limit	Value
`POST /suppressions/bulk`	Suppressions per request	1000

Need Higher Limits?

If you need higher rate limits for your use case, contact us:

Contact Support

Request higher rate limits for your needs

Getting Started

Guides

Concepts

Reference

Rate Limit Overview

Rate Limit Headers

Example Response Headers

Handling Rate Limits

SDK Automatic Retries

Manual Rate Limit Handling

Best Practices

1. Use SDK Auto-Retries

2. Use Batch Endpoints

3. Implement Request Queuing

4. Use Exponential Backoff

Endpoint-Specific Limits

Email Sending

Batch Emails

Suppressions

Need Higher Limits?

Contact Support

Getting Started

Guides

Concepts

Reference

​Rate Limit Overview

​Rate Limit Headers

​Example Response Headers

​Handling Rate Limits

​SDK Automatic Retries

​Manual Rate Limit Handling

​Best Practices

​1. Use SDK Auto-Retries

​2. Use Batch Endpoints

​3. Implement Request Queuing

​4. Use Exponential Backoff

​Endpoint-Specific Limits

​Email Sending

​Batch Emails

​Pagination

​Suppressions

​Need Higher Limits?

Contact Support

Rate Limit Overview

Rate Limit Headers

Example Response Headers

Handling Rate Limits

SDK Automatic Retries

Manual Rate Limit Handling

Best Practices

1. Use SDK Auto-Retries

2. Use Batch Endpoints

3. Implement Request Queuing

4. Use Exponential Backoff

Endpoint-Specific Limits

Email Sending

Batch Emails

Pagination

Suppressions

Need Higher Limits?