Rate Limiting

How rate limiting works on the GPCN™ API, including actual limits, response headers, and strategies for staying within them.

Why Rate Limiting Exists

Rate limits protect the platform from abuse and ensure fair access for everyone. They prevent brute force attacks on authentication endpoints and keep resource-intensive operations from overwhelming the infrastructure.

Rate Limits

Default Limit

All API requests are subject to a default rate limit:

This applies per IP address for unauthenticated requests and per user for authenticated requests.

Authentication Endpoint Limits

Sensitive endpoints have stricter limits to prevent brute force attacks:

Rate Limit Headers

Every API response includes headers that tell you where you stand:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 73
X-RateLimit-Reset: 1703433600

Calculating Time Until Reset

reset=$(curl -sI https://api.gpcn.com/v1/resource/virtual-machines \
  -H "X-API-Key: gpcn_your_api_key_here" | grep -i x-ratelimit-reset | awk '{print $2}' | tr -d '\r')
echo "Limit resets in $(( reset - $(date +%s) )) seconds"

See the API Reference → for examples in TypeScript, Python, Go, and C#.

Handling 429 Responses

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "success": false,
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "You have exceeded the rate limit. Please wait before making more requests.",
  "data": {
    "retryAfter": 45
  }
}

Retry with Exponential Backoff

The best way to handle rate limits is exponential backoff — wait longer between each retry:

for attempt in 1 2 3; do
  response=$(curl -s -w "%{http_code}" -o /tmp/response.json \
    https://api.gpcn.com/v1/resource/virtual-machines \
    -H "X-API-Key: gpcn_your_api_key_here")

  if [ "$response" != "429" ]; then
    cat /tmp/response.json
    break
  fi

  sleep $((2 ** attempt))
done

See the API Reference → for examples in TypeScript, Python, Go, and C#.

Optimizing API Usage

Cache Responses

Don't fetch the same data repeatedly. Cache responses locally, especially for data that changes infrequently like datacenter listings or OS images.

Use Pagination Efficiently

Request larger page sizes when you need many records. One request for 100 items is better than ten requests for 10 items each:

curl "https://api.gpcn.com/v1/resource/virtual-machines?page=1&limit=100" \
  -H "X-API-Key: gpcn_your_api_key_here"

Filter Server-Side

Use query parameters to filter data on the server rather than fetching everything and filtering in your application:

curl "https://api.gpcn.com/v1/resource/virtual-machines?search=production&sort=name:asc" \
  -H "X-API-Key: gpcn_your_api_key_here"

Avoid Polling Loops

If you're waiting for an async operation to complete, use reasonable polling intervals (5–10 seconds). Don't poll every second.

API Keys and Rate Limits

API keys from the same user share the same rate limit pool. If you have two API keys and make 60 requests with each, that's 120 requests against your 100/60s limit — and you'll be rate limited.

Rate limit overrides can be configured per API key by platform administrators. Contact support if you need a higher limit for a specific integration.

Requesting a Quota Increase

If you've optimized your API usage and still regularly hit rate limits, you can request a higher quota.

Contact support with:

• Your current usage pattern and peak request volume
• Which endpoints you're hitting most frequently
• A brief explanation of your use case
• The limit increase you're requesting

The support team will review your request and configure custom limits if appropriate.

Troubleshooting

Next Steps

• Error Codes — full error reference including RATE_LIMIT_EXCEEDED
• Async Operations — polling patterns that respect rate limits
• API Conventions — pagination and filtering to reduce API calls