---
title: Rerun Test Plan
slug: suite-documentation/rerun-test-plan
docTags: 
createdAt: 2026-08-27T07:49:36.785Z
---

The endpoint allows the user to rerun specific scenarios of a test plan.

### Endpoint Information

- **URL**: `{gateway-url}/queue/rerun`
- **Method**: `POST`
- **Authentication**: Required (`Bearer Token`)

### Request Headers

| Header          | Required | Description                                                                               |
| --------------- | -------- | ----------------------------------------------------------------------------------------- |
| `Authorization` | Yes      | Bearer token used to authenticate the request. Format: `Bearer <your_access_token>`.      |
| `Content-Type`  | Yes      | Must be `application/json`.                                                               |
| `X-Company-Id`  | Yes      | Company context for the request. The authenticated user must have access to this company. |

### Request Body

```json
{
  "planId": 704,
  "userId": 1,
  "frameworkType": "SELENIUM4",
  "forceRun": false,
  "scenarioEnvironmentPairs": [
    {
      "scenarioId": 4267,
      "environmentId": 2001
    }
  ]
}
```

### Request Body Parameters

| Parameter                                  | Type    | Required    | Description                                                                                                 |
| ------------------------------------------ | ------- | ----------- | ----------------------------------------------------------------------------------------------------------- |
| `planId`                                   | Long    | Yes         | The unique ID of the test plan to rerun.                                                                    |
| `userId`                                   | Long    | Yes         | The unique ID of the user who triggers the rerun.                                                           |
| `frameworkType`                            | String  | Yes         | Test framework type. Allowed values: `SELENIUM`, `SELENIUM4`, `APPIUM`, `APPIUM2`, `SERVICE`, `PLAYWRIGHT`. |
| `forceRun`                                 | Boolean | No          | Indicates whether the rerun should be forced. Default: `false`.                                             |
| `scenarioEnvironmentPairs`                 | Array   | Yes         | List of scenario/environment pairs to rerun. Must contain at least one item.                                |
| `scenarioEnvironmentPairs[].scenarioId`    | Long    | Yes         | The unique ID of the scenario to rerun.                                                                     |
| `scenarioEnvironmentPairs[].environmentId` | Long    | Conditional | Required for `SELENIUM`, `SELENIUM4`, `APPIUM`, and `APPIUM2`. Optional for `SERVICE` and `PLAYWRIGHT`.     |

### Response

This response indicates that the rerun request was accepted successfully. No additional response data is returned.

\{}

### Error Response Format

```json
{
"instance": "/queue/rerun",
"status": 404,
"title": "Not Found",
"type": "https://errors.testinium.com/exception",
"timestamp": "2026-08-18T12:08:41.165927056Z",
"errorType": "EXCEPTION",
"errors": {
"code": 10002,
"message": "User with id 1666666 not found!"
}
```

### Error Response Fields

| Parameter        | Type            | Description                                                                     |
| ---------------- | --------------- | ------------------------------------------------------------------------------- |
| `instance`       | String          | The request path where the error occurred.                                      |
| `status`         | Integer         | HTTP status code.                                                               |
| `title`          | String          | Short HTTP error title.                                                         |
| `type`           | String          | Error type reference URL.                                                       |
| `timestamp`      | String          | Error timestamp in UTC.                                                         |
| `errorType`      | String          | Internal error category, such as `EXCEPTION`, `VALIDATION`, or `CONFIRMATION`.  |
| `errors`         | Object or Array | Application-level error details. Validation errors may be returned as an array. |
| `errors.code`    | Integer         | Application-specific error code.                                                |
| `errors.message` | String          | Human-readable error message. This may be localized based on request language.  |
| `errors.field`   | String          | Field related to the error. This field may not always be returned.              |

### Error Codes

| HTTP Code | Error Message           | Description                                                                       |
| --------- | ----------------------- | --------------------------------------------------------------------------------- |
| `400`     | `BAD_REQUEST`           | Request body is invalid, malformed, or contains validation errors.                |
| `401`     | `UNAUTHORIZED`          | Bearer token is missing, invalid, or expired.                                     |
| `403`     | `FORBIDDEN`             | The authenticated user does not have permission to access the resource.           |
| `404`     | `NOT_FOUND`             | A referenced resource, such as plan or user, could not be found.                  |
| `409`     | `CONFLICT`              | The plan is already running.                                                      |
| `410`     | `GONE`                  | A referenced entity is disabled or deleted.                                       |
| `422`     | `UNPROCESSABLE_ENTITY`  | The request is syntactically valid but cannot be processed due to business rules. |
| `500`     | `INTERNAL_SERVER_ERROR` | An unexpected server-side error occurred.                                         |
| `503`     | `SERVICE_UNAVAILABLE`   | Gateway or an upstream service is unavailable.                                    |

### Application Error Codes

| Code    | HTTP Status | Source  | Description                                                                                                        |
| ------- | ----------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `10000` | `404`       | Queue   | Plan not found.                                                                                                    |
| `10002` | `404`       | Queue   | User not found.                                                                                                    |
| `10013` | `422`       | Queue   | No scenarios are associated with this plan.                                                                        |
| `10001` | `404`       | Queue   | No environment is associated with this plan.                                                                       |
| `10004` | `410`       | Queue   | Entity is not enabled.                                                                                             |
| `10005` | `410`       | Queue   | Entity is deleted.                                                                                                 |
| `10012` | `409`       | Queue   | Plan is already running.                                                                                           |
| `10008` | `422`       | Queue   | Environment is not registered. Returned with `errorType: CONFIRMATION`.                                            |
| `10007` | `422`       | Queue   | Required app file is missing for the project.                                                                      |
| `10014` | `422`       | Queue   | No build is assigned to the plan.                                                                                  |
| `20005` | `400`       | Common  | Request body validation error, such as missing `planId`, `userId`, `frameworkType`, or `scenarioEnvironmentPairs`. |
| `10001` | `401`       | Gateway | Authentication is required.                                                                                        |
| `10002` | `401`       | Gateway | Token is invalid or malformed.                                                                                     |
| `10003` | `403`       | Gateway | User does not have permission to access the resource.                                                              |
| `10004` | `400`       | Gateway | Required `X-Company-Id` header is missing or malformed.                                                            |
| `10008` | `503`       | Gateway | Routed service is unreachable.                                                                                     |

:::BlockQuote
Note: Application error codes may overlap between services. Use the `Source`, HTTP status, and response message together when interpreting errors.
:::

### Example Request

```curl
curl --location '{{gateway-url}}/queue/rerun' 
--header 'Content-Type: application/json' 
--header 'Authorization: Bearer <your_access_token>' 
--header 'X-Company-Id: <company_id>' 
--data '{
"planId": <plan_id>,
"userId": <user_id>,
"frameworkType": "SELENIUM4",
"forceRun": false,
"scenarioEnvironmentPairs": [
{
"scenarioId": <scenario_id>,
"environmentId": <environment_id>
}
]
}'
```