> ## 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.

# 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 {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

```json theme={null}
{
  "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](#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](#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)

```json theme={null}
{
  "success": true
}
```

When `deploy=true` is specified:

```json theme={null}
{
  "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)

```json theme={null}
{
  "error": "unauthorized_client",
  "error_description": "Invalid token"
}
```

### Error Response (404 Not Found)

```json theme={null}
{
  "error": "not_found",
  "error_description": "ApiProxy (name: MyAPI) was not found!"
}
```

## cURL Example

### Example 1: Configure Status Code Based Error Handling

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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](/api-reference/api-proxies/settings/update-json-error-template) - Configure JSON error response template
* [Update XML Error Template](/api-reference/api-proxies/settings/update-xml-error-template) - Configure XML error response template
* [Update Custom Message](/api-reference/api-proxies/settings/update-custom-message) - Configure custom response message