Rate Limits and Quotas

This section outlines the rate limits, quotas, endpoints, and error-handling rules for the Phoenix Gamification Ingestion Gateway.

Base URLs

Environment	URL(Sample until deployment)
Production	`https://api.phoenix-gamification.com`
Staging	`https://staging-api.phoenix-gamification.com`
Local Development	`http://localhost:3000`

POST /v1/events

Submit an event for processing.

Request:

POST /v1/events HTTP/1.1
Host: api.phoenix-gamification.com
Content-Type: application/json
X-Tenant-Id: acme-corp
X-Signature: hmac-sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Timestamp: 1730113200

{
  "event_id": "evt_12345",
  "event_type": "transaction.completed",
  "tenant_id": "acme-corp",
  "user_id": "user_789",
  "timestamp": "2025-10-28T10:00:00Z",
  "attributes": {
    "amount": 299.99,
    "currency": "USD",
    "product_id": "prod_xyz"
  }
}

Success Response (200 OK):

{
  "status": "accepted",
  "event_id": "evt_12345"
}

Error Response (401 Unauthorized):

{
  "error": "Invalid signature",
  "code": "AUTH_001"
}

GET /health

Health check endpoint (no authentication required).

Response (200 OK):

{
  "status": "healthy"
}

GET /ready

Readiness check with dependency status (no authentication required).

Response (200 OK):

{
  "status": "ready",
  "database": "connected",
  "message_queue": "connected"
}

Error Handling

HTTP Status Codes

Status	Meaning	Action
200	OK	Event accepted successfully
400	Bad Request	Fix request format
401	Unauthorized	Check authentication
403	Forbidden	Contact support (account suspended)
422	Unprocessable Entity	Fix validation errors
429	Too Many Requests	Implement backoff and retry
500	Internal Server Error	Retry with exponential backoff
503	Service Unavailable	Service temporarily down, retry later

Common Error Codes

Code	Description	Resolution
AUTH_001	Invalid signature	Verify signature generation
AUTH_002	Missing header	Include all required headers
AUTH_004	Timestamp expired	Check clock synchronization
AUTH_005	Tenant not found	Verify tenant ID
VAL_001	Missing required field	Include all required event fields
VAL_002	Invalid field format	Check field validation rules
RATE_001	Rate limit exceeded	Implement backoff, reduce request rate

Retry Strategy

Implement exponential backoff for transient errors (5xx, 429):

import time
import random

def send_with_retry(event, max_retries=3):
    for attempt in range(max_retries):
        try:
            return send_event(event)
        except ServerError as e:
            if attempt == max_retries - 1:
                raise

            # Exponential backoff with jitter
            delay = min(60, (2 ** attempt) + random.uniform(0, 1))
            time.sleep(delay)

Rate Limits

Default Limits

Period	Limit
Per second	1,000
Per minute	10,000
Per hour	100,000
Per day	1,000,000

Contact support for higher limits.

Rate Limit Headers

Responses include rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1730113260

Rate Limits and Quotas

On this page