API reference

Rate Limits

GTMCLI enforces rate limits to ensure reliable performance for all users. Limits vary by plan tier and apply per API key.

Limits by Plan

Rate Limit Headers

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

Handling 429 Responses

When you exceed the rate limit, the API returns a 429 Too Many Requests response. Use the Retry-After header to determine when to retry.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 12
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1743868812

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after 12 seconds."
}

import time
import requests

def call_with_retry(url, headers, json, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(url, headers=headers, json=json)
        if resp.status_code == 429:
            wait = int(resp.headers.get("Retry-After", 10))
            time.sleep(wait)
            continue
        return resp
    raise Exception("Rate limit exceeded after retries")

Best Practices

Use batch endpoints. Instead of making 500 individual validate calls, send a single batch request with 500 emails. This counts as 1 request against your rate limit.

Use the Jobs API for large lists. Async jobs bypass per-minute rate limits entirely. Submit your list and get results via polling or webhook.

Implement exponential backoff. When you receive a 429, wait the duration specified in Retry-After, then retry. If you hit the limit again, double the wait time.

Monitor your headers. Check X-RateLimit-Remaining proactively and throttle your requests before hitting the limit.