> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Based Throttling Policy

> API Based Throttling policy limits the number of requests that can be made within a specified time interval. It uses a variable (such as API key, user ID, or IP address) to identify and throttle individual clients.

## General Information

### Policy Type

```plaintext theme={null}
policy-api-based-throttling
```

### Endpoints

#### List Policies

```plaintext theme={null}
GET /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/
```

#### Add Policy

```plaintext theme={null}
POST /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/
```

#### Update Policy

```plaintext theme={null}
PUT /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/
```

#### Delete Policy

```plaintext theme={null}
DELETE /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/
```

***

## List Policies

### Endpoint

```plaintext theme={null}
GET /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/
```

### Request

#### Headers

| Header        | Value            |
| ------------- | ---------------- |
| Authorization | Bearer `{token}` |

#### Path Parameters

| Parameter    | Type   | Required | Description    |
| ------------ | ------ | -------- | -------------- |
| projectName  | string | Yes      | Project name   |
| apiProxyName | string | Yes      | API Proxy name |

### Response

#### Success Response (200 OK)

```json theme={null}
{
  "success": true,
  "resultList": [
    {
      "apiProxy": {
        "name": "MyAPI",
        "requestPolicyList": [
          {
            "type": "policy-api-based-throttling",
            "name": "throttling-policy",
            "description": "API throttling policy",
            "active": true,
            "targetVariableForIdentity": {
              "type": "HEADER",
              "headerName": "X-API-Key"
            },
            "messageCountForInterval": 100,
            "throttlingInterval": "ONE_MINUTE",
            "intervalPeriodLength": 1,
            "intervalWindowType": "FIXED",
            "cacheConnectionTimeoutInSeconds": 3,
            "cacheErrorHandlingType": "FAIL",
            "showRateLimitStatisticsInResponseHeader": false
          }
        ],
        "responsePolicyList": [],
        "errorPolicyList": []
      }
    }
  ],
  "resultCount": 1
}
```

### cURL Example

```bash theme={null}
curl -X GET \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

***

## Add Policy

### Endpoint

```plaintext theme={null}
POST /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/
```

### Request

#### Headers

| Header        | Value            |
| ------------- | ---------------- |
| Authorization | Bearer `{token}` |
| Content-Type  | application/json |

#### Path Parameters

| Parameter    | Type   | Required | Description    |
| ------------ | ------ | -------- | -------------- |
| projectName  | string | Yes      | Project name   |
| apiProxyName | string | Yes      | API Proxy name |
| policyName   | string | Yes      | Policy name    |

#### Request Body

##### Full JSON Body Example

```json theme={null}
{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"],
    "order": 1
  },
  "policy": {
    "type": "policy-api-based-throttling",
    "description": "API throttling policy - 100 requests per minute",
    "active": true,
    "targetVariableForIdentity": {
      "type": "HEADER",
      "headerName": "X-API-Key"
    },
    "messageCountForInterval": 100,
    "throttlingInterval": "ONE_MINUTE",
    "intervalPeriodLength": 1,
    "intervalWindowType": "FIXED",
    "cacheConnectionTimeoutInSeconds": 3,
    "cacheErrorHandlingType": "FAIL",
    "showRateLimitStatisticsInResponseHeader": true,
    "detailList": [
      {
        "targetValue": "VIP",
        "regexExpression": false,
        "messageCountForInterval": 1000,
        "intervalPeriodLength": 1,
        "quotaInterval": "ONE_MINUTE"
      }
    ]
  }
}
```

#### Request Body Fields

##### operationMetadata

| Field                           | Type    | Required | Default | Description                                      |
| ------------------------------- | ------- | -------- | ------- | ------------------------------------------------ |
| targetScope                     | string  | Yes      | -       | Policy scope: `ALL` or `ENDPOINT`                |
| targetEndpoint                  | string  | No\*     | -       | Endpoint path (required if targetScope=ENDPOINT) |
| targetEndpointHTTPMethod        | string  | No\*     | -       | HTTP method (required if targetScope=ENDPOINT)   |
| targetPipeline                  | string  | Yes      | -       | Pipeline: `REQUEST`, `RESPONSE`, or `ERROR`      |
| deploy                          | boolean | No       | true    | Whether to deploy after adding policy            |
| deployTargetEnvironmentNameList | array   | No       | \[]     | List of environment names to deploy to           |
| order                           | integer | No       | null    | Policy execution order (starts from 1)           |

**Enum: targetScope**

* `ALL` - Policy applies to all endpoints
* `ENDPOINT` - Policy applies only to specified endpoint

**Enum: targetPipeline**

* `REQUEST` - Executes in request pipeline
* `RESPONSE` - Executes in response pipeline
* `ERROR` - Executes in error pipeline

**Enum: targetEndpointHTTPMethod**

* `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `OPTIONS`, `HEAD`

##### policy

| Field                                   | Type    | Required | Default | Description                                    |
| --------------------------------------- | ------- | -------- | ------- | ---------------------------------------------- |
| type                                    | string  | Yes      | -       | Policy type: `policy-api-based-throttling`     |
| description                             | string  | No       | -       | Policy description                             |
| active                                  | boolean | No       | true    | Whether policy is active                       |
| targetVariableForIdentity               | object  | Yes      | -       | Variable to identify clients for throttling    |
| messageCountForInterval                 | integer | Yes      | -       | Maximum number of requests allowed in interval |
| throttlingInterval                      | string  | Yes      | -       | Time interval for throttling                   |
| intervalPeriodLength                    | integer | No       | 1       | Period length multiplier                       |
| intervalWindowType                      | string  | No       | FIXED   | Window type: `FIXED` or `SLIDING`              |
| cacheConnectionTimeoutInSeconds         | integer | No       | 3       | Cache connection timeout                       |
| cacheErrorHandlingType                  | string  | No       | FAIL    | Cache error handling: `FAIL` or `ALLOW`        |
| showRateLimitStatisticsInResponseHeader | boolean | No       | false   | Show rate limit stats in response headers      |
| detailList                              | array   | No       | \[]     | List of detail rules for specific values       |

**Enum: throttlingInterval**

* `ONE_SECOND` - 1 second
* `ONE_MINUTE` - 1 minute
* `ONE_HOUR` - 1 hour
* `ONE_DAY` - 1 day

**Enum: intervalWindowType**

* `FIXED` - Fixed time window
* `SLIDING` - Sliding time window

**Enum: cacheErrorHandlingType**

* `FAIL` - Fail request if cache error occurs
* `ALLOW` - Allow request if cache error occurs

##### targetVariableForIdentity

See [Variable Definition](/api-reference/appendix/variable-definition) for complete variable documentation.

| Field              | Type   | Required | Description                                                                                                                   |
| ------------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| name               | string | Yes      | Variable name (e.g., "client.ip", "request.header.X-API-Key")                                                                 |
| type               | string | Yes      | Variable type. See [Variable Types](/api-reference/appendix/variable-definition)                                              |
| headerName         | string | No\*     | Header name (required if type=HEADER)                                                                                         |
| paramType          | string | No\*     | Parameter type (required if type=PARAMETER). See [EnumVariableParameterType](/api-reference/appendix/variable-definition)     |
| paramName          | string | No\*     | Parameter name (required if type=PARAMETER)                                                                                   |
| paramPath          | string | No\*     | Parameter path template (required if type=PARAMETER and paramType=PATH)                                                       |
| messageContentType | string | No\*     | Message content type (required if type=BODY). See [EnumMessageContentType](/api-reference/appendix/variable-definition)       |
| xpathValue         | string | No\*     | XPath expression (required if type=BODY and messageContentType=XML)                                                           |
| jsonPathValue      | string | No\*     | JsonPath expression (required if type=BODY and messageContentType=JSON)                                                       |
| contextValue       | string | No\*     | Context value (required if type=CONTEXT\_VALUES). See [EnumVariableContextValue](/api-reference/appendix/variable-definition) |
| zoneId             | string | No\*     | Time zone ID (required for date/time context values)                                                                          |
| scriptLanguage     | string | No\*     | Script language (required if type=CUSTOM)                                                                                     |
| scriptBody         | string | No\*     | Script body (required if type=CUSTOM)                                                                                         |

### Variable Types

* `HEADER` - Extract from HTTP header
* `PARAMETER` - Extract from query/path/form parameter
* `BODY` - Extract from request body (XML, JSON, or raw)
* `CONTEXT_VALUES` - Extract from system context values (e.g., CLIENT\_IP, REQUEST\_URI)
* `CUSTOM` - Extract using custom script

### Common Context Values

* `REQUEST_REMOTE_ADDRESS` - Client IP address
* `REQUEST_REQUEST_URI` - Request URI
* `REQUEST_HTTP_METHOD` - HTTP method
* `REQUEST_USERNAME_KEY` - Username or key

For complete list of context values, see [EnumVariableContextValue](/api-reference/appendix/variable-definition).

##### detailList (Optional)

| Field                   | Type    | Required | Default | Description                         |
| ----------------------- | ------- | -------- | ------- | ----------------------------------- |
| targetValue             | string  | Yes      | -       | Target value to match (e.g., "VIP") |
| regexExpression         | boolean | No       | false   | Whether targetValue is regex        |
| messageCountForInterval | integer | Yes      | -       | Message count for this detail       |
| intervalPeriodLength    | integer | No       | 1       | Period length multiplier            |
| quotaInterval           | string  | Yes      | -       | Time interval for this detail       |

### Response

#### Success Response (200 OK)

```json theme={null}
{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": [
      {
        "environmentName": "production",
        "success": true,
        "message": "Deployment successful"
      }
    ]
  }
}
```

### cURL Example

```bash theme={null}
curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/throttling-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ALL",
      "targetPipeline": "REQUEST",
      "deploy": true,
      "deployTargetEnvironmentNameList": ["production"],
      "order": 1
    },
    "policy": {
      "type": "policy-api-based-throttling",
      "description": "API throttling policy - 100 requests per minute",
      "active": true,
      "targetVariableForIdentity": {
        "type": "HEADER",
        "headerName": "X-API-Key"
      },
      "messageCountForInterval": 100,
      "throttlingInterval": "ONE_MINUTE",
      "intervalPeriodLength": 1,
      "intervalWindowType": "FIXED",
      "cacheConnectionTimeoutInSeconds": 3,
      "cacheErrorHandlingType": "FAIL",
      "showRateLimitStatisticsInResponseHeader": true
    }
  }'
```

***

## Update Policy

### Endpoint

```plaintext theme={null}
PUT /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/
```

### Request

#### Headers

| Header        | Value            |
| ------------- | ---------------- |
| Authorization | Bearer `{token}` |
| Content-Type  | application/json |

#### Path Parameters

| Parameter    | Type   | Required | Description    |
| ------------ | ------ | -------- | -------------- |
| projectName  | string | Yes      | Project name   |
| apiProxyName | string | Yes      | API Proxy name |
| policyName   | string | Yes      | Policy name    |

#### Request Body

##### Full JSON Body Example

```json theme={null}
{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"],
    "order": 1
  },
  "policy": {
    "type": "policy-api-based-throttling",
    "description": "Updated API throttling policy - 200 requests per minute",
    "active": true,
    "targetVariableForIdentity": {
      "type": "HEADER",
      "headerName": "X-API-Key"
    },
    "messageCountForInterval": 200,
    "throttlingInterval": "ONE_MINUTE",
    "intervalPeriodLength": 1,
    "intervalWindowType": "FIXED",
    "cacheConnectionTimeoutInSeconds": 5,
    "cacheErrorHandlingType": "FAIL",
    "showRateLimitStatisticsInResponseHeader": true,
    "detailList": [
      {
        "targetValue": "VIP",
        "regexExpression": false,
        "messageCountForInterval": 2000,
        "intervalPeriodLength": 1,
        "quotaInterval": "ONE_MINUTE"
      }
    ]
  }
}
```

**Note:** Request body structure is the same as Add Policy. All fields should be provided for update.

### Response

#### Success Response (200 OK)

```json theme={null}
{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": [
      {
        "environmentName": "production",
        "success": true,
        "message": "Deployment successful"
      }
    ]
  }
}
```

### cURL Example

```bash theme={null}
curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/throttling-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ALL",
      "targetPipeline": "REQUEST",
      "deploy": true,
      "deployTargetEnvironmentNameList": ["production"],
      "order": 1
    },
    "policy": {
      "type": "policy-api-based-throttling",
      "description": "Updated API throttling policy - 200 requests per minute",
      "active": true,
      "targetVariableForIdentity": {
        "type": "HEADER",
        "headerName": "X-API-Key"
      },
      "messageCountForInterval": 200,
      "throttlingInterval": "ONE_MINUTE",
      "intervalPeriodLength": 1,
      "intervalWindowType": "FIXED",
      "cacheConnectionTimeoutInSeconds": 5,
      "cacheErrorHandlingType": "FAIL",
      "showRateLimitStatisticsInResponseHeader": true
    }
  }'
```

***

## Delete Policy

### Endpoint

```plaintext theme={null}
DELETE /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/
```

### Request

#### Headers

| Header        | Value            |
| ------------- | ---------------- |
| Authorization | Bearer `{token}` |
| Content-Type  | application/json |

#### Path Parameters

| Parameter    | Type   | Required | Description    |
| ------------ | ------ | -------- | -------------- |
| projectName  | string | Yes      | Project name   |
| apiProxyName | string | Yes      | API Proxy name |
| policyName   | string | Yes      | Policy name    |

#### Request Body

##### Full JSON Body Example

```json theme={null}
{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": false
  }
}
```

#### Request Body Fields

##### operationMetadata

| Field          | Type    | Required | Default | Description                                 |
| -------------- | ------- | -------- | ------- | ------------------------------------------- |
| targetScope    | string  | Yes      | -       | Policy scope: `ALL` or `ENDPOINT`           |
| targetPipeline | string  | Yes      | -       | Pipeline: `REQUEST`, `RESPONSE`, or `ERROR` |
| deploy         | boolean | No       | false   | Whether to deploy after deletion            |

### Response

#### Success Response (200 OK)

```json theme={null}
{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": []
  }
}
```

### cURL Example

```bash theme={null}
curl -X DELETE \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/throttling-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ALL",
      "targetPipeline": "REQUEST",
      "deploy": false
    }
  }'
```

***

## Notes and Warnings

* **Cache Dependency**: This policy requires a cache connection. Ensure cache is properly configured.

* **Identity Variable**: Choose the identity variable carefully. Common choices:
  * `HEADER` with API key header - For API key-based throttling
  * `CONTEXT` with `CLIENT_IP` - For IP-based throttling
  * `PARAMETER` with user ID - For user-based throttling

* **Window Types**:
  * `FIXED` - Fixed time windows (e.g., minute 1:00-1:59)
  * `SLIDING` - Sliding time windows (last 60 seconds from current time)

* **Detail List**: Use detailList to provide different limits for specific values (e.g., VIP users)

* **Rate Limit Headers**: When `showRateLimitStatisticsInResponseHeader` is true, response includes:
  * `X-RateLimit-Limit` - Maximum requests allowed
  * `X-RateLimit-Remaining` - Remaining requests in current window
  * `X-RateLimit-Reset` - Time when limit resets

* **Deployment**: Policy changes require deployment to take effect. Set `deploy: true` or deploy manually.

## Related Documentation

* [List Policies](/api-reference/policies/crud/list-policies) - List all policies
* [Add Policy](/api-reference/policies/crud/add-policy) - General policy addition guide
* [Update Policy](/api-reference/policies/crud/update-policy) - General policy update guide
* [Delete Policy](/api-reference/policies/crud/delete-policy) - General policy deletion guide