API ReferenceRate Limiting

Rate Limiting

The Tewdy API uses rate limiting to ensure fair usage and protect the platform from abuse. Rate limits are applied per user (authenticated) or per IP (unauthenticated).

Rate Limit Headers

Every API response includes headers indicating your current rate limit status:

HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetISO 8601 timestamp when the window resets
Retry-AfterSeconds until the next request is allowed (on 429)

Default Limits

Endpoint TypeLimitWindow
General API100 requests1 minute
API key creation20 requests1 minute
Task creation1 task/day (free)24 hours
Task creation (premium)5 tasks/day24 hours

Handling 429 Errors

When you exceed a rate limit, the API returns a 429 Too Many Requests response:

{
  "message": "Too many requests, please try again later.",
  "status": 429
}

Best Practices

  1. Check the headers. Before retrying, read X-RateLimit-Remaining to know if you’re close to the limit.

  2. Use the Retry-After header. When you receive a 429, wait the number of seconds indicated before retrying.

  3. Implement exponential backoff. For automated systems, use exponential backoff with jitter:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
 
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '5', 10);
      const delay = retryAfter * 1000 * Math.pow(2, attempt) + Math.random() * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }
 
    return response;
  }
 
  throw new Error('Max retries exceeded');
}

  1. Cache responses. For read-heavy workloads, cache task data locally to reduce API calls.

  2. Batch operations. Where possible, fetch multiple resources in a single request using query parameters rather than making individual requests.

Rate Limits for API Keys

API key requests count against the authenticated user’s rate limit, not a separate API key limit. This means requests made via JWT and API key share the same quota.

TasksError Codes