Rate Limiters

Rate limiters allow you to control the rate at which Taskhook executes callbacks for your tasks. Use rate limiters to ensure you respect 3rd party API rate limits, manage resource utilization, or control the flow of webhook executions. Rate limiters don't limit the rate at which you can call Taskhook APIs.

Understanding rate limiters

Rate limiters provide several key capabilities:

• Define rate limiting rules that can be applied to any task
• Support various rate limiting algorithms for different use cases
• Apply rate limits across all your tasks, schedules, and batches
• Monitor rate limit usage and receive notifications
• Dynamically adjust limits as needed

Create a rate limiter

curl https://api.taskhook.io/v1/rate-limiters \
  -H "Authorization: Bearer {token}" \
  -d '{
    "name": "stripe-api",
    "type": "window",
    "description": "Rate limit for Stripe API calls",
    "config": {
      "limit": 100,
      "interval": 60
    },
    "timeouts": {
      "queue_timeout": 300,
      "validity_timeout": 3600
    }
  }'

{
  "id": "rl_123abc",
  "name": "stripe-api",
  "type": "window",
  "description": "Rate limit for Stripe API calls",
  "config": {
    "limit": 100,
    "interval": 60
  },
  "timeouts": {
    "queue_timeout": 300,
    "validity_timeout": 3600
  },
  "created_at": "2024-01-30T12:00:00Z",
  "updated_at": "2024-01-30T12:00:00Z"
}

Get a rate limiter

curl https://api.taskhook.io/v1/rate-limiters/rl_123abc \
  -H "Authorization: Bearer {token}"

{
  "id": "rl_123abc",
  "name": "stripe-api",
  "type": "window",
  "description": "Rate limit for Stripe API calls",
  "config": {
    "limit": 100,
    "interval": 60
  },
  "timeouts": {
    "queue_timeout": 300,
    "validity_timeout": 3600
  },
  "created_at": "2024-01-30T12:00:00Z",
  "updated_at": "2024-01-30T12:00:00Z"
}

List rate limiters

curl -G https://api.taskhook.io/v1/rate-limiters \
  -H "Authorization: Bearer {token}" \
  -d limit=10

{
  "total": 2,
  "rate_limiters": [
    {
      "id": "rl_123abc",
      "name": "stripe-api",
      "type": "window",
      "config": {
        "limit": 100,
        "interval": 60
      },
      "created_at": "2024-01-30T12:00:00Z"
    },
    {
      "id": "rl_456def",
      "name": "shopify-api",
      "type": "leaky",
      "config": {
        "capacity": 100,
        "drain_rate": 10,
        "interval": 1
      },
      "created_at": "2024-01-30T12:00:00Z"
    }
  ]
}

Update a rate limiter

curl -X PATCH https://api.taskhook.io/v1/rate-limiters/rl_123abc \
  -H "Authorization: Bearer {token}" \
  -d '{
    "description": "Updated rate limit for Stripe API",
    "config": {
      "limit": 150,
      "interval": 60
    }
  }'

{
  "id": "rl_123abc",
  "name": "stripe-api",
  "type": "window",
  "description": "Updated rate limit for Stripe API",
  "config": {
    "limit": 150,
    "interval": 60
  },
  "timeouts": {
    "queue_timeout": 300,
    "validity_timeout": 3600
  },
  "created_at": "2024-01-30T12:00:00Z",
  "updated_at": "2024-01-30T12:30:00Z"
}

Delete a rate limiter

curl -X DELETE https://api.taskhook.io/v1/rate-limiters/rl_123abc \
  -H "Authorization: Bearer {token}"

{
  "deleted": true,
  "id": "rl_123abc"
}

Using rate limiters

To apply a rate limiter to tasks, reference it by name in your task creation:

{
  "target": "https://api.stripe.com/v1/charges",
  "rate_limiter": "stripe-api",
  "execute_after": "2024-02-01T00:00:00Z",
  "valid_until": "2024-02-01T01:00:00Z",
  ...
}

For schedules and batches, include it in the task template:

{
  "task_template": {
    "target": "https://api.stripe.com/v1/charges",
    "rate_limiter": "stripe-api",
    ...
  }
}

When using points-based rate limiting, you can specify the cost per task:

{
  "target": "https://api.github.com/graphql",
  "rate_limiter": "github-api",
  "points_cost": 5,
  ...
}

Best practices

1. Naming conventions: Use descriptive names that identify the API or resource being rate limited (e.g., "stripe-api", "github-graphql").

2. Timeout configuration:

   • Set queue_timeout based on your application's latency requirements
   • Set validity_timeout to prevent execution of stale tasks
   • Consider downstream API timeout configurations

3. Rate limit selection:

   • Use concurrent for strict parallel operation limits
   • Use window for standard API rate limits
   • Use leaky bucket when bursting is acceptable
   • Use points for complex API quotas

4. Monitoring: Monitor rate limiter metrics to adjust configurations:

   • Queue depth and wait times
   • Task expiration rates
   • Rate limit utilization

Limitations

• Names must be unique within your account
• Names can only contain letters, numbers, and hyphens
• Certain rate limiter types may not be available on all plans

Rate limiter deletion

When a rate limiter is deleted:

• Queued tasks using the limiter will execute without rate limiting
• New tasks cannot be created referencing the deleted limiter
• Historical data is retained for 30 days