API Reference: Methods, Error Schema, and Status Handling

This page documents method-based limits, the error response schema, and how status codes are used by the rate limiter.

Rate-limit headers

Every rate-limited response includes the following headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-ResetOn: 1713091800000

X-RateLimit-ResetOn is a Unix timestamp in milliseconds for when the limit resets. Clients should treat it as the earliest retry time.

Method-based limits

The persistent configuration schema supports a method field. When present, the override applies only to that HTTP method. If method is omitted, the override applies to all methods for the endpoint.

Example override for POST only:

{
  "ip": "192.168.1.100",
  "endpoint": "/api/orders",
  "userTier": "premium",
  "method": "POST",
  "algorithm": "TOKEN_BUCKET",
  "parameters": {
    "capacity": 20,
    "refillRate": 5
  }
}

If you store a POST-specific override and a generic override for the same endpoint and tier, the behavior depends on your resolution order. Prefer one override per endpoint + tier + method to avoid ambiguity.

Response schema for error bodies

When the service returns JSON errors, it uses this schema:

{
  "errorCode": "SERVICE_UNAVAILABLE",
  "errorMessage": "Redis connection failed",
  "errorType": "RedisConnectionFailureException",
  "timestamp": "2024-04-13T10:30:00Z"
}

errorCode is a stable enum-like string. errorType is the exception class. timestamp is ISO-8601.

The 429 response body is currently plain text, not JSON, and reads:

All requests have been exhausted. Try again later!!!

If you need a structured 429 body, add a custom error handler and keep the headers consistent so clients can still back off correctly.

Status handling

The rate limiter uses these status codes:

X-RateLimit-* headers are only set when the rate limiter executes a decision. Validation errors and infrastructure failures may not include them.

Configuration endpoints

POST /api/config (in-memory)

Stores configuration in the in-memory store. This is per-instance and lost on restart.

{
  "ip": "192.168.1.100",
  "algo": "TOKEN_BUCKET",
  "endpoint": "/api/test",
  "method": "GET",
  "parameters": {
    "capacity": 20,
    "refillRate": 5
  }
}

POST /api/config/v2 (MongoDB)

Stores configuration in MongoDB with the schema shown above. This override has higher priority than YAML.

{
  "ip": "192.168.1.100",
  "endpoint": "/api/test",
  "userTier": "premium",
  "method": "GET",
  "algorithm": "TOKEN_BUCKET",
  "parameters": {
    "capacity": 50,
    "refillRate": 10
  }
}

This endpoint is excluded from rate limiting by default, so protect it with authentication and its own rate limit at the gateway or by removing it from the exclusion list.