Anton.Docs
Dashboard (opens in a new tab)
How it works

Rate limits

Every authenticated response tells you your limit, what is left and when it resets. A 429 tells you how long to wait.

Two kinds of limit apply. Read the headers on any response to see how close you are to a limit. Back off when you get a 429.

LimitApplies to
100 requests a secondEach IP address, across the whole API
120 requests a minuteEach merchant, on /v1/intelligence/*
60 requests a minuteEach merchant, on POST /v1/webhooks/{id}/test

A few other endpoints, such as exports and FX quotes, carry tighter limits of their own. These numbers can change; the headers always show the limit that applies, and they are the contract.

Headers

Every authenticated response carries:

HeaderValue
X-RateLimit-LimitMaximum requests permitted in the current window.
X-RateLimit-RemainingRequests remaining in the current window.
X-RateLimit-ResetUnix timestamp when the current window resets.

If Anton cannot check your limit for a moment, it serves the request and leaves these three headers out rather than guess. Treat a response without them as "limit unknown", not "unlimited", and keep your own pacing.

Over the limit, Anton returns 429 with one more header:

HeaderValue
Retry-AfterSeconds to wait before retrying.

Response body:

JSON
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "rate limit exceeded, retry after 60 seconds",
    "doc_url": "https://docs.antonpayments.com/api-reference/errors#rate_limit_exceeded",
    "request_id": "req_01JD3XB7Q2"
  }
}

Handling 429

Treat 429 as transient and wait at least Retry-After seconds before retrying. When many requests are waiting, add jitter: retrying them all at the same instant trips the limiter again. A 503 also carries Retry-After.

retry() {
  local url=$1
  for attempt in 1 2 3 4 5; do
    # dpop_proof builds a fresh proof for each attempt
    response=$(curl -sS -D /tmp/hdr -o /tmp/body -w "%{http_code}" "$url" \
      -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \
      -H "DPoP: $(dpop_proof GET "$url")")
    if [ "$response" != "429" ]; then
      cat /tmp/body
      return 0
    fi
    retry_after=$(grep -i '^retry-after:' /tmp/hdr | awk '{print $2}' | tr -d '\r')
    sleep "${retry_after:-1}"
  done
  echo "rate limit: retry budget exhausted" >&2
  return 1
}

Needing a higher limit

If sustained traffic keeps hitting your ceiling, contact help.antonpayments.com with your use case and expected volume.

Something wrong or missing here? Open an issue (opens GitHub in a new tab) ↗