Best Practices: JumpCloud API

Read this article for guidance on retrying failed requests to JumpCloud's REST API, as well as best practices for structuring subsequent retry requests. Customizing retry mechanisms based on these recommendations will increase the reliability and dependability of your API calls.


  • JumpCloud currently utilizes two versions of APIs. Depending on the type of integration, it may be required to use both V1 and V2 APIs. Please refer to each API doc to understand the functionality available in that API set.

Supported HTTP Request Methods

  • GET
  • POST
  • PUT

Response codes

  • 200, 201, 202, 204
  • 302, 303, 304
  • 400, 401, 402, 403, 404, 406, 409, 410, 412, 415, 422, 428, 429
  • 500, 502, 503, 504

API Key Rotation

Because API keys are utilized in the development of solutions that interact with the JumpCloud API, and thus are sometimes shared, there are opportunities for these private API keys to be compromised.

Best security practice strongly encourages the API Key associated with your JumpCloud Administrator account to be rotated & re-generated on a periodic rolling basis. While specific security needs and risks will vary for your organization, it’s generally recommended to re-create the API keys on an annual basis. Note that once an API key is rotated, the older key will be invalidated. Code that leverages older API keys will fail and will need to be updated with the new key.


When paginating results with "skip" or querying with a "filter", it is highly recommended that you also add "sort" : "_id" to the query parameters. Sorting will ensure that you receive all and only the requested data (i.e., no missing or duplicate results). If you choose to sort by a different field, be sure that field contains unique values.


Sorting on fields that contain duplicate values may return a different sort order for those duplicate fields over multiple executions, especially when the collection is actively receiving writes.

Error Handling

Request errors, regardless of source, can be categorized as Permanent or Temporary errors.

Permanent errors

Permanent errors will cause a request to always fail. Examples of Permanent errors include:

  • Authentication failures: An unauthorized API key is used to authenticate the request
  • Incorrect request type: An unsupported HTTP request operator at a given endpoint is being used 
  • Unsupported request: The request itself cannot be processed, often due to missing or unsupported data values in the request

Temporary errors

Temporary errors will cause a request to fail temporarily or intermittently. Examples of temporary errors include:

  • Service Outage
  • Service Maintenance
  • Rate limiting

An example of a temporary error would be an HTTP error in the 5xx class. This error can be surfaced if the request is made to an endpoint that may be currently unavailable.

Based on the category of error, the Retry rate & strategy can be determined. This is outlined in the following section: Retry rates

Retry Rates

All network components can be responsible for returning errors. These errors are commonly derived from network hiccups on the server or client, a service disruption on incident, or scheduled maintenance. 

Retry mechanisms are useful for increased reliability and consistency when leveraging JumpCloud APIs. Should a request return an error, correctly configured retry mechanisms ensure that the failed request is retried with consideration to the error response.

The following table outlines retry recommendations based on error classification:

Error CodeDefinitionRecommendation
4xx ClassClient errorImmediate retry not recommended. Issue lies within the request itself.
429Rate limit exceededApply sufficient backoff; retry with a considerably less frequent request rate before scaling.
5xx ClassServer errorApply sufficient backoff; retry with a less frequent request rate. Refer to for a possible maintenance window, or incident before scaling.

Retry Intervals

Retry requests should always feature a longer interval than the previous retry attempt. Best practice is to implement an exponential backoff to specify exact timing increases between retry requests. An example implementation of an exponential backoff would be to retry the request shortly after a failed attempt. Subsequent requests are recommended to be executed on an exponential basis. For example, if the specified retry interval is 30 seconds, the first retry occurs after 30 seconds. The second retry should occur after 60 seconds, the third retry after 120 seconds, the forth after 240 seconds, and so on. Inadequate retry intervals can prove detrimental for both troubleshooting and client-side error handling.

In addition to these guidelines, several consecutive failed requests should warrant further investigation within the request code before retry is attempted. 


A JumpCloud service returns “403 Forbidden. Your IP has been blocked due to suspected abuse.”


When accessing a JumpCloud Service endpoint, the connection returns an error:

403 Forbidden. Your IP has been blocked due to suspected abuse, please contact [email protected] in order to get this issue resolved.


This error is returned when an IP has been blocked due to suspected abuse. 


Contact JumpCloud Support so we can work with you regarding the reasons for the block and action needed to unblock the IP(s).

Calling the “GET /api/commandresults” API endpoint returns “503 Service Unavailable”.


When calling the GET /api/commandresults in the JumpCloud V1 API, the system returns an error: 503 (Service Unavailable).


This API endpoint will timeout and return an error if it takes too long to list all of the command results. The timeout can occur depending on how many command results exist in the org, the complexity of the request, and the current load on the database.


  • If your org has a large quantity of devices and commands, delete command results that are no longer needed and try again.
  • Reduce the frequency of read requests for command results in your API query and try again.
  • If the issue persists, try running the query at a later time when there is less load on the server.
Back to Top

List IconIn this Article

Notebook IconLearn More

Still Have Questions?

If you cannot find an answer to your question in our FAQ, you can always contact us.

Submit a Case