API: Error handling - TestRail

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.