bamboohr-common-errors

# 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. ```typescript 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:** ```bash # 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 encodin...