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 due to invalid credentials. |
| 403 | Access denied, likely due to 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. |
Rate Limit
Please note that the API is rate limited on TestRail Cloud 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.
Rate limits for TestRail Cloud are as follows:
-
180 Requests per instance, per minute for standard subscriptions.
-
300 Requests per instance, per minute for Enterprise subscriptions.