BambooHR Common Errors Skill

BambooHR Common Errors

Overview

Diagnostic reference for BambooHR REST API errors. BambooHR returns error details in the X-BambooHR-Error-Message response header for most 400-level and some 500-level errors.

Prerequisites

BambooHR API access configured
Access to application logs or HTTP response headers

Instructions

Step 1: Read the Error Header

Always check X-BambooHR-Error-Message first — it contains BambooHR's specific error detail, which is more useful than generic HTTP status text.

const res = await fetch(`${BASE}/employees/999/`, {
  headers: { Authorization: AUTH, Accept: 'application/json' },
});

if (!res.ok) {
  const errorDetail = res.headers.get('X-BambooHR-Error-Message');
  console.error(`HTTP ${res.status}: ${errorDetail || res.statusText}`);
}

Step 2: Match Error to Solution

401 Unauthorized — Invalid API Key

X-BambooHR-Error-Message: Invalid API key

Cause: API key is missing, expired, revoked, or malformed in the Basic Auth header.

Solution:

# Verify key is set
echo "Key length: ${#BAMBOOHR_API_KEY}"

# Test auth directly
curl -s -o /dev/null -w "%{http_code}" \
  -u "${BAMBOOHR_API_KEY}:x" \
  "https://api.bamboohr.com/api/gateway.php/${BAMBOOHR_COMPANY_DOMAIN}/v1/employees/directory"

Common mistakes:

Using Bearer token instead of Basic Auth
Putting the API key as the password instead of the username
Missing the :x password part in Basic Auth encoding

403 Forbidden — Insufficient Permissions

X-BambooHR-Error-Message: You do not have access to this resource

Cause: The API key's user account lacks permissions for the requested endpoint or employee.

Solution:

Verify the user's access level in BambooHR (Account > Access Levels)
Time-off management endpoints require manager or admin permissions
Compensation table access requires admin permissions
Some fields are restricted to specific access levels

400 Bad Request — Invalid Fields or Payload

X-BambooHR-Error-Message: Invalid field: "jobTitl"

Cause: Misspelled field name, invalid date format, or malformed JSON body.

Solution:

# Verify field names against BambooHR's field list
curl -s -u "${BAMBOOHR_API_KEY}:x" \
  "https://api.bamboohr.com/api/gateway.php/${BAMBOOHR_COMPANY_DOMAIN}/v1/employees/0/?fields=firstName,lastName" \
  -H "Accept: application/json"

Common field name mistakes:

title (wrong) vs jobTitle (correct)
email (wrong) vs workEmail (correct)
name (wrong) vs firstName + lastName (correct)
Date format must be YYYY-MM-DD, not MM/DD/YYYY

404 Not Found — Wrong Endpoint or ID

X-BambooHR-Error-Message: Employee not found

Cause: Employee ID does not exist, wrong company domain, or malformed URL path.

Solution:

# Verify company domain
echo "Domain: $BAMBOOHR_COMPANY_DOMAIN"

# Verify the base URL structure
# Correct:  /api/gateway.php/{domain}/v1/employees/{id}/
# Wrong:    /api/v1/employees/{id}/
# Wrong:    /api/gateway.php/{domain}/employees/{id}/  (missing /v1/)

429 / 503 — Rate Limited

HTTP 503 with Retry-After: 30

Cause: Too many requests in a short period. BambooHR does not publish exact rate limits but returns 503 with a Retry-After header.

Solution:

async function handleRateLimit(res: Response): Promise<void> {
  if (res.status === 503 || res.status === 429) {
    const retryAfter = parseInt(res.headers.get('Retry-After') || '30', 10);
    console.warn(`Rate limited. Waiting ${retryAfter}s...`);
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  }
}

Prevention:

Batch reads using custom reports instead of individual employee GETs
Cache directory results (they change infrequently)
Use /employees/changed/?since=... for incremental sync instead of full pulls

500 / 502 — Server Errors

Cause: BambooHR internal error. Usually transient.

Solution:

Check BambooHR Status Page for outages
Retry with exponential backoff (see bamboohr-rate-limits)
If persistent, collect request details for BambooHR support

Content-Type Mismatch

Cause: Missing Accept: application/json header — BambooHR defaults to XML.

# Wrong — returns XML
curl -u "${BAMBOOHR_API_KEY}:x" \
  "${BASE}/employees/directory"

# Correct — returns JSON
curl -u "${BAMBOOHR_API_KEY}:x" \
  -H "Accept: application/json" \
  "${BASE}/employees/directory"

Step 3: Quick Diagnostic Script

#!/bin/bash
echo "=== BambooHR Diagnostic ==="
echo "Company: ${BAMBOOHR_COMPANY_DOMAIN}"
echo "Key set: ${BAMBOOHR_API_KEY:+YES}"
echo "Key length: ${#BAMBOOHR_API_KEY}"

BASE="https://api.bamboohr.com/api/gateway.php/${BAMBOOHR_COMPANY_DOMAIN}/v1"

echo -n "Auth test: "
STATUS=$(curl -s -o /dev/null -w "%{http_code}" -u "${BAMBOOHR_API_KEY}:x" \
  -H "Accept: application/json" "${BASE}/employees/directory")
echo "$STATUS"

echo -n "Status page: "
curl -s https://status.bamboohr.com | head -c 100
echo ""

if [ "$STATUS" -eq 200 ]; then
  echo "Connection OK"
elif [ "$STATUS" -eq 401 ]; then
  echo "FIX: Regenerate API key in BambooHR dashboard"
elif [ "$STATUS" -eq 403 ]; then
  echo "FIX: Upgrade API key user's access level"
elif [ "$STATUS" -eq 404 ]; then
  echo "FIX: Check BAMBOOHR_COMPANY_DOMAIN value"
else
  echo "FIX: Check status page and retry"
fi

Output

Identified error from HTTP status + X-BambooHR-Error-Message header
Applied fix based on error category
Verified resolution with diagnostic script

Error Summary Table

| Status | Header | Root Cause | Fix | |--------|--------|-----------|-----| | 400 | Invalid field | Typo in field name | Check field list docs | | 401 | Invalid API key | Bad credentials | Regenerate API key | | 403 | No access | Insufficient permissions | Upgrade user access level | | 404 | Not found | Wrong ID or domain | Verify URL components | | 429/503 | Retry-After | Rate limited | Backoff and retry | | 500/502 | — | Server error | Retry; check status page |

Resources

Next Steps

For comprehensive debugging, see bamboohr-debug-bundle.

Agent Skills: BambooHR Common Errors

Install this agent skill to your local

Skill Files