⏱️Rate Limits

Our API employs rate limiting to ensure fair usage and to prevent abuse. Gangmates employs layered rate limiting to protect tenants and the platform. There are two buckets evaluated per request:

1. Endpoint Bucket (per token + IP + route)

   • Default: 100 requests/min

   • Sensitive endpoints: 10 requests/min (listed below)

2. Global Bucket (per company + IP)

   • Standard: 50 requests/min

   • Premium: 1,000 requests/min

   • Enterprise: 5,000 requests/min

The effective limit is the stricter of the two. For example, a Standard plan calling a non‑sensitive endpoint is limited to 50/min globally, even though the endpoint bucket allows 100/min.

Response headers

Every response includes rate‑limit headers so you can programmatically back off:

X-RateLimit-Limit-Endpoint: <int>
X-RateLimit-Remaining-Endpoint: <int>
X-RateLimit-Limit-Global: <int>
X-RateLimit-Remaining-Global: <int>

On 429 Too Many Requests, you’ll also receive:

Retry-After: <seconds>

429 handling (pseudo‑code)

if response.status == 429:wait(response.headers['Retry-After'] seconds)retry

Add jitter/exponential backoff in production clients.

Errors

Standard HTTP status codes are used.

• 200 OK – Success

• 201 Created – Resource created

• 400 Bad Request – Invalid request

• 401 Unauthorized – Missing/invalid/expired token

• 403 Forbidden – Token scopes do not allow this route

• 404 Not Found – Resource not found

• 429 Too Many Requests – Rate limit exceeded (see Retry-After)

Error bodies are JSON. Examples:

{ "error": "Unauthorized" }

Examples

Here are examples of how you can implement this retry logic in different programming languages:

JavaScript (Axios)

const axios = require('axios');

async function makeApiRequest(url, options) {
    try {
        const response = await axios(url, options);
        return response.data;
    } catch (error) {
        if (error.response && error.response.status === 429) {
            // Extract the Retry-After header value
            const retryAfter = parseInt(error.response.headers['retry-after'], 10);

            if (!isNaN(retryAfter)) {
                console.log(`Rate limit exceeded. Retrying after ${retryAfter} seconds...`);
                await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
                return makeApiRequest(url, options); // Retry the request
            } else {
                console.error('Rate limit exceeded but no Retry-After header found.');
            }
        } else {
            console.error('Request failed:', error.message);
        }
    }
}

// Example usage
const url = 'https://api.example.com/your-endpoint';
const options = {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer your_token_here'
    }
};

makeApiRequest(url, options)
    .then(data => {
        console.log('API Response:', data);
    })
    .catch(error => {
        console.error('Request failed:', error.message);
    });
            

Python (Requests)

import time
import requests

def make_api_request(url, headers):
    try:
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as err:
        if err.response.status_code == 429:
            retry_after = int(err.response.headers.get('Retry-After', 0))
            if retry_after > 0:
                print(f'Rate limit exceeded. Retrying after {retry_after} seconds...')
                time.sleep(retry_after)
                return make_api_request(url, headers)
            else:
                print('Rate limit exceeded but no Retry-After header found.')
        else:
            print(f'Request failed: {err}')

# Example usage
url = 'https://api.example.com/your-endpoint'
headers = {
    'Authorization': 'Bearer your_token_here'
}

response_data = make_api_request(url, headers)
if response_data:
    print('API Response:', response_data)
            

Java (HttpClient)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class ApiClient {
    private static final HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .build();

    public static String makeApiRequest(String url, String token) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
                .uri(new URI(url))
                .header("Authorization", "Bearer " + token)
                .GET()
                .build();

        HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() == 429) {
            String retryAfterHeader = response.headers().firstValue("Retry-After").orElse("0");
            int retryAfter = Integer.parseInt(retryAfterHeader);

            if (retryAfter > 0) {
                System.out.println("Rate limit exceeded. Retrying after " + retryAfter + " seconds...");
                Thread.sleep(retryAfter * 1000);
                return makeApiRequest(url, token);
            } else {
                System.out.println("Rate limit exceeded but no Retry-After header found.");
            }
        }

        return response.body();
    }

    public static void main(String[] args) {
        String url = "https://api.example.com/your-endpoint";
        String token = "your_token_here";

        try {
            String response = makeApiRequest(url, token);
            System.out.println("API Response: " + response);
        } catch (Exception e) {
            System.err.println("Request failed: " + e.getMessage());
        }
    }
}
            

By implementing the above retry mechanism, your application can handle rate limiting gracefully, ensuring that your requests are processed once the rate limit resets. If you have any questions or need further assistance, please contact our support team at [email protected].