Update Error Handling Settings

Updates error handling settings for an API proxy. Error handling settings control how the gateway responds when backend errors occur.

​

Endpoint

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

​

Authentication

Requires a Personal API Access Token.

​

Header

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.

​

Related Documentation

• 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