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.
| Limit | Applies to |
|---|---|
| 100 requests a second | Each IP address, across the whole API |
| 120 requests a minute | Each merchant, on /v1/intelligence/* |
| 60 requests a minute | Each 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:
| Header | Value |
|---|---|
X-RateLimit-Limit | Maximum requests permitted in the current window. |
X-RateLimit-Remaining | Requests remaining in the current window. |
X-RateLimit-Reset | Unix 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:
| Header | Value |
|---|---|
Retry-After | Seconds to wait before retrying. |
Response body:
{
"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.