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 Limit Details

• Limit: 1 request per 2 seconds per organization
• Scope: Organization-based (all users in the same organization share the limit)
• Window: 2-second sliding window

How It Works

1. API Key Request: When you make a request with an API key, the system identifies your organization
2. Rate Check: The system checks if your organization has exceeded the rate limit
3. Request Processing: If within limits, the request is processed; if exceeded, a 429 error is returned
4. Reset: The rate limit resets after the 2-second window

Response Headers

Rate-limited responses include these headers for monitoring:

X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200000
Retry-After: 1

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 2 seconds - blocked
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.swiftia.com/v1/jobs
# Returns: 429 Rate limit exceeded

# Wait 2+ seconds, then retry - allowed
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.swiftia.com/v1/jobs

Rate Limit by Authentication Type

Monitoring

Track your rate limit usage through response headers:

• X-RateLimit-Limit: Maximum requests allowed (1)
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Timestamp when the limit resets
• Retry-After: Seconds to wait before retrying