bamboohr-rate-limits

name	bamboohr-rate-limits
description	Implement BambooHR rate limiting, backoff, and request optimization. Use when handling 429/503 rate limit errors, implementing retry logic, or optimizing API request throughput for BambooHR. Trigger with phrases like "bamboohr rate limit", "bamboohr throttling", "bamboohr 429", "bamboohr 503", "bamboohr retry", "bamboohr backoff".
allowed-tools	Read, Write, Edit
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","hr","bamboohr","rate-limiting"]
compatible-with	claude-code

BambooHR Rate Limits

Overview

BambooHR does not publish exact rate limits, but the API returns 503 Service Unavailable with a Retry-After header when you exceed them. This skill covers detection, backoff, request optimization, and queue-based throttling.

Prerequisites

• BambooHR API client configured
• Understanding of async/await patterns

Instructions

Step 1: Understand BambooHR Rate Limiting Behavior

BambooHR rate limiting details:

Signal	Value	Description
HTTP Status	503	Primary rate limit signal
Retry-After header	seconds (e.g., 30)	How long to wait before retrying
X-BambooHR-Error-Message	varies	May contain rate limit detail
HTTP Status 429	rare	Some endpoints return 429 for employee count limits

Key insight: BambooHR uses 503 (not 429) for rate limiting. Failed authentication attempts also count toward rate limits, so ensure your API key is valid before making many requests.

Step 2: Implement Retry-After Aware Backoff

import { BambooHRApiError } from './client';

interface RetryConfig {
  maxRetries: number;
  baseDelayMs: number;
  maxDelayMs: number;
}

const DEFAULT_RETRY: RetryConfig = {
  maxRetries: 5,
  baseDelayMs: 1000,
  maxDelayMs: ,
};

  withBambooHRRetry<T>(
  :  <T>,
  config = ,
): <T> {
   ( attempt = ; attempt <= config.; attempt++) {
     {
        ();
    }  (err) {
       (attempt === config.)  err;
       (!(err  ))  err;
       (!err.)  err; 

      
       : ;
       (err..) {
        delay = (err.., ) * ;
      }  {
        
         exponential = config. * .(, attempt);
         jitter = .() * config.;
        delay = .(exponential + jitter, config.);
      }

      .(
         +
        
      );
        ( (r, delay));
    }
  }
    ();
}