Update Error Handling Settings - Apinizer Dokümantasyonu

Endpoint

PATCH /apiops/projects/{projectName}/apiProxies/{apiProxyName}/settings/error-handling/

Authentication

Requires a Personal API Access Token.

Authorization: Bearer YOUR_TOKEN

Request

Headers

Header	Value	Required
Authorization	Bearer	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

{
  "errorHandlingType": "STATUS_CODE_LIST",
  "statusCodeList": [500, 502, 503, 504],
  "customizeErrorMessageEnabled": true,
  "errorMessageList": [
    {
      "httpStatusCode": 500,
      "customizedHttpStatusCode": 503,
      "customizedErrorCode": "BACKEND_ERROR",
      "customizedMessage": "Service is temporarily unavailable"
    },
    {
      "httpStatusCode": 502,
      "customizedHttpStatusCode": 502,
      "customizedErrorCode": "BAD_GATEWAY",
      "customizedMessage": "Bad gateway response from backend"
    }
  ],
  "deploy": false,
  "deployTargetEnvironmentNameList": []
}

Request Body Fields

Field	Type	Required	Default	Description
errorHandlingType	string	No	DEFAULT	Error handling strategy. See EnumErrorHandlingType
statusCodeList	array[integer]	No	-	List of HTTP status codes that trigger custom error handling
customizeErrorMessageEnabled	boolean	No	false	Enable custom error messages for matching status codes
errorMessageList	array[object]	No	-	List of custom error message definitions. See Error Message Object
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)

EnumErrorHandlingType

DEFAULT - Use default error handling (pass through backend errors)
ADVANCED - Advanced error handling with full customization
STATUS_CODE_LIST - Custom handling for specific HTTP status codes only

Error Message Object

Field	Type	Required	Description
httpStatusCode	integer	Yes	Original HTTP status code to match
customizedHttpStatusCode	integer	No	Replacement HTTP status code to return to client
customizedErrorCode	string	No	Custom error code string
customizedMessage	string	No	Custom error message text

Note: All fields are optional. Only provided fields are updated.

Response

Success Response (200 OK)

{
  "success": true
}

When deploy=true is specified:

{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": [
      {
        "environmentName": "production",
        "success": true,
        "message": "Deployment successful"
      }
    ]
  }
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful
deploymentResult	object	Only present when `deploy=true`
deploymentResult.success	boolean	Overall deployment success status
deploymentResult.deploymentResults	array	Per-environment deployment results

Error Response (401 Unauthorized)

{
  "error": "unauthorized_client",
  "error_description": "Invalid token"
}

Error Response (404 Not Found)

{
  "error": "not_found",
  "error_description": "ApiProxy (name: MyAPI) was not found!"
}

cURL Example

Example 1: Configure Status Code Based Error Handling

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/error-handling/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "errorHandlingType": "STATUS_CODE_LIST",
    "statusCodeList": [500, 502, 503],
    "customizeErrorMessageEnabled": true,
    "errorMessageList": [
      {
        "httpStatusCode": 500,
        "customizedHttpStatusCode": 503,
        "customizedErrorCode": "SERVICE_UNAVAILABLE",
        "customizedMessage": "Service is temporarily unavailable"
      }
    ]
  }'

Example 2: Reset to Default Error Handling

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/error-handling/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "errorHandlingType": "DEFAULT"
  }'

Example 3: Enable Advanced Error Handling with Custom Messages

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/error-handling/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "errorHandlingType": "ADVANCED",
    "customizeErrorMessageEnabled": true,
    "errorMessageList": [
      {
        "httpStatusCode": 500,
        "customizedHttpStatusCode": 500,
        "customizedErrorCode": "INTERNAL_ERROR",
        "customizedMessage": "An internal error occurred. Please try again later."
      },
      {
        "httpStatusCode": 502,
        "customizedHttpStatusCode": 502,
        "customizedErrorCode": "BAD_GATEWAY",
        "customizedMessage": "The backend service returned an invalid response."
      },
      {
        "httpStatusCode": 504,
        "customizedHttpStatusCode": 504,
        "customizedErrorCode": "GATEWAY_TIMEOUT",
        "customizedMessage": "The backend service did not respond in time."
      }
    ]
  }'

Example 4: Save and Deploy

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/error-handling/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "errorHandlingType": "STATUS_CODE_LIST",
    "statusCodeList": [500, 502, 503],
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"]
  }'

Notes and Warnings

Error Handling Types:
- DEFAULT: Backend error responses are passed through to the client without modification
- ADVANCED: All backend errors are intercepted and custom error messages are applied
- STATUS_CODE_LIST: Only the specified HTTP status codes trigger custom error handling
Custom Messages: When customizeErrorMessageEnabled=true, matching errors use the customized message and status code
Error Message Matching: Error messages are matched by httpStatusCode — if a backend returns a status code in the list, the corresponding custom message is used
Partial Updates: You can update individual fields without affecting others
Deploy: When deploy=true, the API proxy is automatically deployed to the specified environments after saving

Permissions

User must have API_MANAGEMENT + MANAGE permission in the project.

Update JSON Error Template - Configure JSON error response template
Update XML Error Template - Configure XML error response template
Update Custom Message - Configure custom response message

Home

​Endpoint

​Authentication

​Header

​Request

​Headers

​Path Parameters

​Request Body

​Full JSON Body Example

​Request Body Fields

​EnumErrorHandlingType

​Error Message Object

​Response

​Success Response (200 OK)

​Response Fields

​Error Response (401 Unauthorized)

​Error Response (404 Not Found)

​cURL Example

​Example 1: Configure Status Code Based Error Handling

​Example 2: Reset to Default Error Handling

​Example 3: Enable Advanced Error Handling with Custom Messages

​Example 4: Save and Deploy

​Notes and Warnings

​Permissions

​Related Documentation