Rate Limiting

Swiftia API implements rate limiting to ensure fair usage and prevent abuse. Rate limits are applied per organization when using API keys. Rate limits vary based on your subscription plan - paid plans have higher rate limits.

Rate Limit Details

Rate limits are determined by your organization's active subscription plan:

• Scope: Organization-based (all users in the same organization share the limit)
• Window: Sliding window (varies by plan)

How It Works

1. API Key Request: When you make a request with an API key, the system identifies your organization
2. Plan Detection: The system determines your organization's active subscription plan
3. Rate Check: The system checks if your organization has exceeded the plan-specific rate limit
4. Request Processing: If within limits, the request is processed; if exceeded, a 429 error is returned
5. Reset: The rate limit resets after the plan-specific window duration

Response Headers

Rate-limited responses include these headers for monitoring:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 5
X-RateLimit-Reset: 1640995200000
Retry-After: 1

The X-RateLimit-Limit header reflects your plan's rate limit (e.g., 1 for Free/Starter/Pro, 5 for Swift).

Error Response

When rate limit is exceeded:

{
  "status": 429,
  "message": "Rate limit exceeded. Please try again later.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 1
}

Best Practices

• Implement exponential backoff when receiving 429 responses
• Monitor rate limit headers to track usage
• Plan request timing to stay within limits
• Use session authentication for web app requests (no rate limiting)

Example Usage

# First request - allowed
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.swiftia.com/v1/jobs

# Second request within window - blocked (varies by plan)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.swiftia.com/v1/jobs
# Returns: 429 Rate limit exceeded

# Wait for window to reset, then retry - allowed
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.swiftia.com/v1/jobs

Rate Limit by Authentication Type

Upgrading Your Plan

To increase your API rate limits, upgrade to a paid plan:

• Starter Plan: Faster requests (1 request per 2 seconds vs 5 seconds for Free)
• Pro Plan: Even faster requests (1 request per 1 second)
• Swift Plan: Highest throughput (5 requests per 1 second)

Rate Limit Comparison:

• Free: 1 request every 5 seconds (12 requests/minute)
• Starter: 1 request every 2 seconds (30 requests/minute)
• Pro: 1 request every 1 second (60 requests/minute)
• Swift: 5 requests every 1 second (300 requests/minute)

Rate limits are automatically updated when you upgrade or downgrade your subscription plan.

Monitoring

Track your rate limit usage through response headers:

• X-RateLimit-Limit: Maximum requests allowed (varies by plan: 1 for Free/Starter/Pro, 5 for Swift)
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Timestamp when the limit resets
• Retry-After: Seconds to wait before retrying