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.