Rate Limits

Manage your API usage efficiently. Learn about rate limits per plan, how to monitor your consumption, and best practices for handling throttling.

💡

Why Rate Limits?

Rate limits ensure fair usage, maintain service stability, and protect our infrastructure. They allow Dictionary to provide consistent performance for all users.

Overview

Dictionary API implements rate limiting based on your subscription plan. Limits are applied per API key and measured in requests per minute (RPM) and requests per day (RPD). Each API response includes headers that indicate your current rate limit status.

Rate Limits by Plan

The following table outlines the rate limits for each subscription tier:

Plan	Requests / Minute	Requests / Day	Burst Allowance	Concurrent Requests
Free Active	60 RPM	1,000 RPD	10 requests	2
Pro Popular	600 RPM	50,000 RPD	50 requests	10
Enterprise Custom	Custom	Unlimited	Custom	Custom

API Response Headers

Every API response includes headers that provide information about your rate limit status. Use these headers to monitor your usage and avoid hitting limits.

Header	Description
`X-RateLimit-Limit`	The maximum number of requests allowed per minute for your current plan.
`X-RateLimit-Remaining`	The number of requests remaining in the current rate limit window.
`X-RateLimit-Reset`	The Unix timestamp when the rate limit window resets.
`X-RateLimit-Daily-Remaining`	The number of requests remaining for the current day.
`Retry-After`	Seconds to wait before retrying (only present in 429 responses).

Example Response Headers

HTTP Headers

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 452
X-RateLimit-Reset: 1678901234
X-RateLimit-Daily-Remaining: 48230

{
  "word: "ephemeral",
  "definitions: [...]
}

Handling Rate Limit Exceeded

When you exceed your rate limit, the API returns an HTTP 429 Too Many Requests status code. The response body includes an error object with details about the limit.

⚠️

Important

Always check the Retry-After header in 429 responses. Wait for the specified duration before retrying to avoid further delays.

429 Error Response

JSON

HTTP/1.1 429 Too Many Requests
Retry-After: 15

{
  "error: {
    "code: "rate_limit_exceeded",
    "message: "You have exceeded your rate limit. Please retry after 15 seconds.",
    "retry_after: 15
  }
}

Best Practices

Implement Exponential Backoff: When you receive a 429 error, wait for the duration specified in Retry-After, then retry. If you continue to hit limits, increase the wait time exponentially.
Cache Responses: For frequently requested words, cache the responses locally to reduce API calls.
Monitor Headers: Regularly check X-RateLimit-Remaining to anticipate when you're approaching your limit.
Batch Requests: If your use case allows, batch multiple lookups into a single request where possible.
Use Webhooks: For asynchronous operations, use webhooks to avoid polling the API repeatedly.

Need Higher Limits?

If your application requires higher rate limits than what your current plan offers, consider upgrading your subscription or contact our sales team for a custom Enterprise solution.

Upgrade Plan Contact Sales