API
Rate Limits

Rate Limits

The Onvera API implements rate limiting to ensure fair usage and system stability.

Rate Limit Headers

All API responses include rate limit headers:

  • X-RateLimit-Limit - Maximum requests per window
  • X-RateLimit-Remaining - Remaining requests in current window
  • X-RateLimit-Reset - Unix timestamp when the rate limit resets

Example:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705766400

Default Limits

Per API Key

  • 1000 requests per hour - Default limit per API key
  • Burst limit - Up to 100 requests per minute

Per Endpoint

Some endpoints have specific limits:

  • Operation polling - Recommended: 1 request per 2-5 seconds
  • Deployment creation - 10 deployments per hour

Rate Limit Exceeded

When you exceed the rate limit, the API returns:

Status Code: 429 Too Many Requests

Response:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 60 seconds"
  }
}

Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705766400
Retry-After: 60

Handling Rate Limits

Exponential Backoff

When you receive a 429 response, implement exponential backoff:

import time
import random
 
def make_request_with_backoff(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        
        if response.status_code != 429:
            return response
        
        # Get retry delay from header or calculate
        retry_after = int(response.headers.get('Retry-After', 60))
        
        # Add jitter to avoid thundering herd
        delay = retry_after + random.uniform(0, 10)
        
        print(f"Rate limited. Retrying after {delay} seconds...")
        time.sleep(delay)
    
    raise Exception("Max retries exceeded")

Respect Retry-After Header

Always respect the Retry-After header:

# Get retry delay from header
RETRY_AFTER=$(curl -I -H "X-API-Key: $API_KEY" \
  https://api.onvera.io/api/v1/deployments \
  2>/dev/null | grep -i "retry-after" | cut -d' ' -f2)
 
# Wait before retrying
sleep $RETRY_AFTER

Best Practices

  1. Monitor rate limit headers - Track remaining requests
  2. Implement exponential backoff - For 429 responses
  3. Respect Retry-After header - Wait the specified time
  4. Don't poll too frequently - Use 2-5 second intervals for operations
  5. Cache responses - Reduce unnecessary requests
  6. Batch operations - When possible, batch multiple operations

Polling Guidelines

When polling operations:

  • Recommended interval: 2-5 seconds
  • Maximum frequency: 1 request per second
  • Don't poll indefinitely - Set a timeout (e.g., 30 minutes)

Example:

#!/bin/bash
 
OPERATION_ID="op_xxx"
API_KEY="onv_sk_live_..."
MAX_ATTEMPTS=360  # 30 minutes at 5 second intervals
 
for i in $(seq 1 $MAX_ATTEMPTS); do
  RESPONSE=$(curl -s -H "X-API-Key: $API_KEY" \
    https://api.onvera.io/api/v1/operations/$OPERATION_ID)
  
  STATUS=$(echo $RESPONSE | jq -r '.data.status')
  
  if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ]; then
    echo "Operation completed: $STATUS"
    break
  fi
  
  # Wait 5 seconds before next poll
  sleep 5
done

Increasing Limits

If you need higher rate limits, contact your account representative to discuss your use case and requirements.

Related Concepts

ErrorsOpenAPI Specification