Update Error Handling Settings

Endpoint

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

Warning

This endpoint returns HTTP 400 for API proxies with type=AI. In earlier releases it returned 200 OK but had no effect (a silent no-op) — this is a behavior change and existing CI/CD pipelines that call this endpoint against AI proxies may be affected.

The AI proxy runtime does not read the classic routing object; the equivalent configuration lives under aiRouting. Use Update AI Routing instead.

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

{
  "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)

{
  "status": "FAILURE",
  "resultMessage": "Token is not valid!"
}

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