API: Error handling
The API signals errors via standard HTTP status codes. This means that successful responses use a 2xx status code whereas errors are reported with 4xx or 5xx.
Applications and libraries that use TestRail’s API are responsible for handling 5xx errors and are supposed to retry requests later in this case. 4xx errors are client-side errors and usually indicate an incorrect or incomplete request, e.g. trying to read a test case that doesn’t exist or using an invalid request format. With each of the status codes below, the body of the response will include additional details pertaining to the success or failure of the request.
| Response Code | Description |
| 200 | Success. |
| 400 | The requested entity does not exist, or the body of the POST request is not properly formatted. |
| 401 | Authentication failed, likely because of invalid credentials. |
| 403 | Access denied, likely because of insufficient permissions. |
| 404 | The API endpoint does not exist. |
| 409 | Account is undergoing daily maintenance (TestRail Cloud only). |
| 429 | API rate limit reached (TestRail Cloud only). |
| 500 | Server error. |
API Rate Limit
Please note that the API is rate-limited on TestRail Cloud to ensure optimal performance for all users and may throttle requests. TestRail might also return a 429 Too Many Requests response, which you are expected to handle. Such a response also includes a Retry-After header indicating how many seconds to wait before you are allowed to submit the next request.
To avoid rate limits on TestRail Cloud, try using bulk API endpoints (e.g. using as add_results_for_cases instead of add_results_for case), build a time delay into your API calls, or upgrade to TestRail Enterprise Cloud.
Rate limits for TestRail Cloud are as follows:
-
180 Requests per instance, per minute for TestRail Cloud Professional subscriptions.
-
300 Requests per instance, per minute for TestRail Cloud Enterprise subscriptions.
No API rate limits are built into TestRail Server installations.