Skip to Content
LightRateAPI Reference

API Reference

Authentication

All API calls require an API key in the x-api-key header.

Keep your API key secure! Never commit it to version control or expose it in client-side code.

Base URL

  • Production: https://api.lightrate.lightbournetechnologies.ca/api

Consume Tokens

Consume tokens from a token bucket to enforce rate limiting.

Endpoint

POST /v1/tokens/consume

Headers

Content-Type: application/json
x-api-key: your-api-key

Request Body

ParameterTypeRequiredDescription
applicationIdstringYesYour application ID
userIdentifierstringYesUnique identifier for the user/client being rate limited
tokensRequestednumberYesNumber of tokens to consume (typically 1)
operationstringNoOperation name for operation-based rules
pathstringNoHTTP path for path-based rules (requires httpMethod)
httpMethodstringNoHTTP method (required if path is provided)

Provide either operation OR both path and httpMethod, or neither to use the application’s default rate limit.

Example Request

POST /v1/tokens/consume
Content-Type: application/json
x-api-key: your-api-key
 
{
  "applicationId": "app_123",
  "userIdentifier": "user_456",
  "operation": "sendEmail",
  "tokensRequested": 5
}

Response

Success (200 OK):

{
  "tokensRemaining": 37,
  "tokensConsumed": 5,
  "rule": {
    "id": "rule_abc123",
    "name": "Send Email",
    "refillRate": 10,
    "burstRate": 100,
    "isDefault": false
  }
}

Rate Limit Exceeded (200 OK):

{
  "tokensRemaining": 0,
  "tokensConsumed": 0,
  "rule": {
    "id": "rule_abc123",
    "name": "Send Email",
    "refillRate": 10,
    "burstRate": 100,
    "isDefault": false
  }
}

Usage Examples

Application Default Rate Limiting

Use the application’s default token bucket when you don’t specify an operation or path:

curl -X POST "https://api.lightrate.com/v1/tokens/consume" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "applicationId": "app_123",
    "userIdentifier": "user_456",
    "tokensRequested": 1
  }'

Operation-Based Rate Limiting

Rate limit by operation name (useful for non-HTTP operations):

curl -X POST "https://api.lightrate.com/v1/tokens/consume" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "applicationId": "app_123",
    "userIdentifier": "user_456",
    "operation": "sendEmail",
    "tokensRequested": 1
  }'

Path-Based Rate Limiting

Rate limit by HTTP path and method:

curl -X POST "https://api.lightrate.com/v1/tokens/consume" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "applicationId": "app_123",
    "userIdentifier": "user_456",
    "path": "/api/users",
    "httpMethod": "POST",
    "tokensRequested": 1
  }'

Error Handling

Common Error Responses

401 Unauthorized:

Missing or invalid API key.

{
  "error": "Invalid API key"
}

400 Bad Request:

Missing required fields or invalid parameters.

{
  "error": "Missing required fields: must provide applicationId, userIdentifier, tokensRequested"
}

404 Not Found:

Application not found or you don’t have access to it.

{
  "error": "Application not found or access denied"
}

200 OK (Rate Limited):

Rate limit exceeded - no tokens available.

{
  "tokensRemaining": 0,
  "tokensConsumed": 0,
  "rule": {
    "id": "rule_abc123",
    "name": "Send Email",
    "refillRate": 10,
    "burstRate": 100,
    "isDefault": false
  }
}

Error Handling Best Practices

  1. Check tokensConsumed - If tokensConsumed > 0, proceed with your operation. If it’s 0, the request was rate limited
  2. Handle rate limiting gracefully - Display user-friendly messages when rate limits are exceeded
  3. Use exponential backoff - Wait before retrying after hitting rate limits
  4. Monitor tokensRemaining - Use this field to implement client-side throttling
  5. Log rate limiting - Keep track of rate limiting occurrences for debugging and monitoring

Next Steps

Last updated on
Ruby