Gorgias rate limits: 40 req/20s on API keys, 80 on OAuth2; honor the 429 headers

TL;DR: If you run multiple workers or integrations, give each its own API key so they dont share a bucket. Read the two headers on every response and pace yourself instead of hardcoding limits; Gorgias has adjusted these numbers over time and enterprise windows differ. On a 429, sleep for the Retry-after value and retry, with a small jitter.

Gorgias rate limits: 40 req/20s on API keys, 80 on OAuth2; honor the 429 headers

Fix

1. If you run multiple workers or integrations, give each its own API key so they dont share a bucket. Expected: this specific failure stops.

2. OAuth2 apps get 80 requests in a 20 second window, API key integrations get 40 in 20 seconds, and enterprise accounts use a smaller 10 second window. Expected: this specific failure stops.

3. Every response carries Retry-after (seconds to wait) and X-Gorgias-Account-Api-Call-Limit (usage like 35/40) headers. Expected: this specific failure stops.

Details

Read the two headers on every response and pace yourself instead of hardcoding limits; Gorgias has adjusted these numbers over time and enterprise windows differ. On a 429, sleep for the Retry-after value and retry, with a small jitter. Request the max 100 records per page so you burn fewer calls. Context: Official docs (Rate Limits): documents that the Gorgias API uses a leaky-bucket limit keyed by auth type. Exceeding it returns 429 Too Many Requests. The budget is also shared across anything calling the API with the same credentials, so two integrations on one key can starve each other.

When to use

You hit exactly this: Gorgias rate limits: 40 req/20s on API keys, 80 on OAuth2; honor the 429 headers in Gorgias rate limits.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Gorgias rate limits.

Root cause

And treat 40 per 20 seconds as generous headroom for a sync job, not for a chatty polling loop.

Source: Official docs (Rate Limits): documents that the Gorgias API uses a leaky-bucket limit keyed by auth type. OAuth2 apps get 80 requests in a 20 second window, API key integrations get 40 in 20 seconds, and enterprise accounts use a smaller 10 second window. Exceeding it returns 429 Too Many Requests. Every response carries Retry-after (seconds to wait) and X-Gorgias-Account-Api-Call-Limit (usage like 35/40) headers. The budget is also shared across anything calling the API with the same credentials, so two integrations on one key can starve each other.

Verified resolution: Read the two headers on every response and pace yourself instead of hardcoding limits; Gorgias has adjusted these numbers over time and enterprise windows differ. On a 429, sleep for the Retry-after value and retry, with a small jitter. Request the max 100 records per page so you burn fewer calls. If you run multiple workers or integrations, give each its own API key so they dont share a bucket. And treat 40 per 20 seconds as generous headroom for a sync job, not for a chatty polling loop.

Source URL: https://developers.gorgias.com/reference/limitations