Error Handling

Testmo uses HTTP status codes to indicate if API calls were successful or have failed. Successful API calls return a 2xx response (typically a 200 OK). API calls with errors are represented by 4xx (client-side errors) and 5xx (server-side errors) status codes.

Typical HTTP status codes for errors include 401 (authentication problems such as invalid API tokens), 403 (invalid permissions), 404 (unknown or deleted objects) or 429 (API rate limit reached).

The following table lists typical HTTP error status codes that Testmo API methods return:

HTTP status codeTypeExample



Invalid or missing Testmo API token



Missing or insufficient permissions


Not found

Unknown or deleted objects in API requests


Method not allowed

Using GET instead of POST or vice versa


Invalid data

Invalid parameters or data in API requests


Too many requests

Rate limit reached (please see below)

Rate limits & throttling

If you send more than a typical amount of API requests at once or in a short period of time, Testmo may throttle or limit API requests. Testmo returns a 429 status code for API requests that were denied due to reaching a rate limit. Such responses include a Retry-After header with the minimum amount of time to wait before sending another request (if the Retry-After header is not included in the response, you should at least wait for 60 seconds).

If you plan to send a large amount of API requests, please consider adding small wait times between API requests to avoid rate limits. Hitting the rate limit too many times may also result in longer periods of 429 responses or might even (temporarily) limit the API for your Testmo account.

Sending many test results?

Testmo's API supports sending many test results at once in bulk, so you do not need to send a request for each test result. So make sure to send test results in bulk to avoid hitting any rate limits.

Also consider using our Testmo CLI tool to send your test results instead of using the API directly. Our CLI tool automatically sends test results in bulk and comes with many other useful features built on top of the API.

Last updated