API Errors & Troubleshooting

The article provides guidance on troubleshooting API request failures by using error codes and messages. It includes a table of contents outlining HTTP status codes, which are categorized into successful (2xx), client error (4xx), and server error (5xx) codes. Each category is explained with examples and suggested actions for resolution. For instance, a 400 error indicates a bad request, while a 500 error signifies an internal server issue. The article emphasizes the importance of examining the response header, particularly the "X-BambooHR-Error-Message" for additional context. It also encourages users to contact customer support for assistance and includes a link to the full API documentation for further reference.

  • May 12, 2026
  • Knowledge

Title
API Errors & Troubleshooting
Article Text
This feature is included in the Core, Pro, and Elite packages.

If an API request fails, you can use the error code and message to identify the issue and fix it. This guide explains common errors and how to resolve them.

Expand AllCollapse All

Table of Contents

View our full API documentation, including detailed error responses: https://documentation.bamboohr.com/docs/api-details 

Some errors include a response header called "X-BambooHR-Error-Messsage." (The extra 's' is intentional.)

This message can help identify the issue during development or troubleshooting, but it may change over time and should not be used for programmatic error handling.

HTTP status codes

Every request includes an HTTP status code with the result. The status code should be examined before the response.

Successful status codes (2xx)
CodeWhat It Means
200: OKThe request was successful.
201: CreatedThe resource was successfully created. This confirms a success when creating a new employee, time off request, or similar resource.
Client error status codes (4xx)
Error CodeWhat It MeansWhat to Check
400: Bad RequestThe request was invalid or could not be understood by the server. Resubmitting the request will likely result in the same error.
  • Review the "X-BambooHR-Error-Messsage" header to view more information.
401: UnauthorizedThe request is missing an API key.
  • Confirm the API key is included correctly.
  • Verify the key is valid.
403: ForbiddenThe application is attempting to perform an action it does not have permission to access.
  • Make sure the API key is enabled.
  • Verify the user has access to the request data.
404: Not FoundThe resource was not found with the given identifier. The given URL or the ID of the object specified in the request is invalid. It can also be that the method (GET, POST, PUT, DELETE) is unavailable.
  • Confirm the endpoint URL is correct.
  • Verify the resource ID is valid.
406: Not AcceptableThe request contains references to non-existent fields.
  • Review field names and values
  • Remove or correct invalid fields
409: ConflictThe request attempts to create a duplicate resource. (Duplicate emails and list values are not allowed.)
  • Ensure the data being submitted is unique.
  • Review existing records.
429: Limit ExceededThe account has reached its employee limit. No additional employees can be added.
  • Review your account limits.
  • Adjust the request or account configuration.
Server error status codes (5xx)
Error CodeWhat It MeansWhat to Check
500: Internal Server ErrorThe server encountered an error while processing your request.
  • Retry the request.
  • If the issue continues, contact our Support team.
502: Gateway ErrorThe load balancer or web server had trouble connecting to the BambooHR application.
  • Retry the request.
  • Check for temporary service issues.
503: Service UnavailableThe endpoint is temporarily unavailable. This can happen when requests are too frequent.
  • Check for a Retry-After header that tells you how long you should wait before retrying.

API support

If you are running into issues with API calls, getting unexpected responses, or just need help understanding how something works, our Support team is here to help.

Please reach out to our Customer Support team and include as much of the following information as possible so we can assist you quickly:

  • The exact API call you are making (including the full endpoint and any parameters or filters)
  • The payload (if applicable)
  • Your BambooHR domain (for example, yourcompanyname.bamboohr.com)
  • The last four digits of your API key and the user associated with your request

Including these details helps our Support team verify your access and pinpoint issues faster.

You can future-proof your code by using the following ranges:

  • 200-299 as success codes
  • 400-499 as client request errors
  • 500-599 as server errors
URL Name
587843