Update Idempotency Settings

Endpoint

PATCH /apiops/projects/{projectName}/apiProxies/{apiProxyName}/settings/idempotency/

Authentication

Requires a Personal API Access Token.

Header

Authorization: Bearer YOUR_TOKEN

Request

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes
Content-Type	application/json	Yes

Path Parameters

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

Request Body

Full JSON Body Example

{
  "idempotencySettings": {
    "name": "Idempotency Settings",
    "description": "Idempotency-Key configuration",
    "idempotencyActive": true,
    "keyType": "HEADER",
    "headerName": "Idempotency-Key",
    "keyRequired": false,
    "missingKeyHttpStatus": 400,
    "applicableHttpMethods": ["POST", "PUT", "PATCH", "DELETE"],
    "payloadHashEnabled": true,
    "processingTimeoutInSeconds": 60,
    "retentionInDays": 7,
    "cacheStorageType": "DISTRIBUTED",
    "handlingAction": "CONTINUE",
    "cacheConnectionTimeoutInSeconds": 3,
    "conflictHttpStatus": 409,
    "mismatchHttpStatus": 422,
    "replayCompletedResponse": true,
    "conflictMessage": "{\"error\":\"idempotency_conflict\",\"message\":\"A request with this Idempotency-Key is already being processed.\"}",
    "mismatchMessage": "{\"error\":\"idempotency_payload_mismatch\",\"message\":\"This Idempotency-Key was already used with a different request payload.\"}",
    "missingKeyMessage": "{\"error\":\"idempotency_key_required\",\"message\":\"The Idempotency-Key header is required.\"}",
    "errorContentType": "application/json",
    "missingKeyBodyEnabled": true,
    "conflictBodyEnabled": true,
    "mismatchBodyEnabled": true,
    "variableList": []
  },
  "deploy": false,
  "deployTargetEnvironmentNameList": []
}

Request Body Fields

Field	Type	Required	Default	Description
idempotencySettings	object	No	-	Idempotency settings object (see fields below)
deploy	boolean	No	false	If true, deploy the API proxy after saving changes
deployTargetEnvironmentNameList	array[string]	No	-	List of environment names to deploy to (required when deploy=true)

idempotencySettings Fields

Field	Type	Required	Default	Description
name	string	No	-	Settings name
description	string	No	-	Settings description
idempotencyActive	boolean	No	false	Enable/disable idempotency handling
keyType	string	No	HEADER	HEADER or CUSTOM
headerName	string	No	Idempotency-Key	Header name when keyType=HEADER
variableList	array	No	[]	Custom key variables when keyType=CUSTOM
keyRequired	boolean	No	false	Reject requests missing the idempotency key
missingKeyHttpStatus	integer	No	400	HTTP status when key is required but missing
applicableHttpMethods	array[string]	No	POST, PUT, PATCH, DELETE	HTTP methods subject to idempotency
payloadHashEnabled	boolean	No	true	Hash request payload to detect mismatches
processingTimeoutInSeconds	integer	No	60	In-flight processing lock timeout
retentionInDays	integer	No	7	Completed entry retention (1–30)
cacheStorageType	string	No	DISTRIBUTED	LOCAL or DISTRIBUTED
handlingAction	string	No	-	CONTINUE or STOP when cache hit occurs
cacheConnectionTimeoutInSeconds	integer	No	3	Distributed cache connection timeout
conflictHttpStatus	integer	No	409	HTTP status for in-flight duplicate
mismatchHttpStatus	integer	No	422	HTTP status for payload mismatch
replayCompletedResponse	boolean	No	true	Replay stored response for completed keys
conflictMessage	string	No	(built-in JSON)	Custom conflict response body
mismatchMessage	string	No	(built-in JSON)	Custom mismatch response body
missingKeyMessage	string	No	(built-in JSON)	Custom missing-key response body
errorContentType	string	No	application/json	Content-Type for custom error bodies
missingKeyBodyEnabled	boolean	No	true	Include body on missing-key response
conflictBodyEnabled	boolean	No	true	Include body on conflict response
mismatchBodyEnabled	boolean	No	true	Include body on mismatch response

Partial update behavior

This endpoint applies only the fields present in the request body. Omitting a field, or sending it as null, keeps the value that is currently stored — including a setting an operator deliberately turned off. To change a value you must send it explicitly; false, 0 and an empty string are explicit values, not omissions.

The Default column above applies only when the settings object is created for the first time. On a proxy that already has these settings, an omitted field keeps its stored value, not the default.

List fields are replaced as a whole: an omitted list keeps the stored list, and an explicitly empty list ([]) clears it.

Clients that read the settings and send the complete object back keep working unchanged; properties the endpoint does not recognise are ignored rather than rejected.

EnumIdempotencyKeyType

• HEADER — Extract key from an HTTP header (headerName)
• CUSTOM — Build key from variableList

EnumCacheStorageType

• LOCAL — Local cache (per worker instance)
• DISTRIBUTED — Distributed cache (shared across all workers)

EnumCacheHandlingAction

• CONTINUE — Return cached response and continue to backend (for logging/monitoring)
• STOP — Return cached response and stop processing

Response

Success Response (200 OK)

{
  "status": "SUCCESS",
  "deploymentResult": {
    "success": true,
    "responseTime": 1500,
    "detailList": [
      {
        "envName": "production",
        "success": true,
        "detail": "Deployed successfully",
        "responseTime": 450
      }
    ]
  }
}

When deploy is false or omitted, deploymentResult.success may be false with an empty detailList.

Error Responses

Status	Condition
400	Validation failure or proxy not found
401	Invalid or missing token
500	Unexpected server error

cURL Example

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyApiProxy/settings/idempotency/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencySettings": {
      "idempotencyActive": true,
      "keyType": "HEADER",
      "headerName": "Idempotency-Key"
    },
    "deploy": false
  }'

Partial Update (Change One Field)

Only retentionInDays is sent, so the other settings — the key type, the header name, the applicable methods and all three custom error bodies — keep the values stored on the proxy.

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyApiProxy/settings/idempotency/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencySettings": {
      "retentionInDays": 14
    }
  }'

Notes and Warnings

• Applies to all proxy types, including AI, MCP, and A2A proxies.
• retentionInDays is constrained to 1–30 at the model level.
• Set deploy: true with deployTargetEnvironmentNameList to push changes to Gateway environments in the same call.

Permissions

User must have API_MANAGEMENT + MANAGE permission in the project. Deployment requires API_MANAGEMENT + DEPLOY_UNDEPLOY.

Related Documentation

• Update Cache Settings
• API Proxy Settings
• Deploy API Proxy