Rate limits and versions

The HowdyBell API enforces rate limits to ensure fair usage and stability. It also uses a versioning header to track API changes.

Rate Limits

Rate limits are applied per API key. If you exceed the limit, the API returns a 429 status code.

Limits

• Limit: 120 requests per minute.
• Scope: Per API key, or per app install for requests made with an OAuth access token.
• Reset: The counter resets every minute.

429 Response

When you exceed the limit, the response looks like this:

{
  "message": "Too Many Attempts."
}

Every response also carries X-RateLimit-Limit and X-RateLimit-Remaining, and a 429 adds Retry-After (seconds).

Handling 429 Errors

1. Stop Making Requests: Immediately halt further API calls.
2. Wait: Pause for the number of seconds in Retry-After.
3. Retry: Resume requests after the wait period.
4. Implement Backoff: Use exponential backoff for repeated failures.

Example backoff logic:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const waitTime = Math.pow(2, i) * 1000;
      console.log(`Rate limited. Waiting ${waitTime}ms...`);
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}

API Versioning

The API includes a version header in every response. This helps you track which version of the API you are using.

Version Header

• Header Name: X-HowdyBell-Version
• Current Value: 2026-09-22

Example Response Headers

HTTP/1.1 200 OK
Content-Type: application/json
X-HowdyBell-Version: 2026-09-22

Why Versioning Matters

1. Compatibility: The version header indicates the API contract.
2. Debugging: Log the version header to correlate issues with specific API releases.
3. Migration: When HowdyBell releases a new version, you can detect it via this header.

Note: The version header is present on all responses, including errors and rate limit responses.

Best Practices

1. Monitor Usage: Track your request volume to stay under the 120/minute limit.
2. Cache Responses: Store data locally to reduce API calls.
3. Log Version Headers: Include the X-HowdyBell-Version header in your logs.
4. Handle 429s Gracefully: Do not crash your application when rate limited.

Troubleshooting

If you are consistently hitting rate limits:

1. Check for Loops: Ensure your code is not making redundant calls.
2. Optimize Queries: Use filters to reduce the number of results fetched.
3. Contact Support: If you need a higher limit, email [email protected].