Ana içeriğe atla

​
Endpoint

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

​
Authentication

Requires a Personal API Access Token. 
Authorization: Bearer YOUR_TOKEN

​
Request

​
Headers

HeaderValueRequired
AuthorizationBearer Yes
Content-Typeapplication/jsonYes

​
Path Parameters

ParameterTypeRequiredDescription
projectNamestringYesProject name
apiProxyNamestringYesAPI 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"
    }
  ]
}

​
Request Body Fields

FieldTypeRequiredDefaultDescription
errorHandlingTypestringNoDEFAULTError handling strategy. See EnumErrorHandlingType
statusCodeListarray[integer]No-List of HTTP status codes that trigger custom error handling
customizeErrorMessageEnabledbooleanNofalseEnable custom error messages for matching status codes
errorMessageListarray[object]No-List of custom error message definitions. See Error Message Object

​
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

FieldTypeRequiredDescription
httpStatusCodeintegerYesOriginal HTTP status code to match
customizedHttpStatusCodeintegerNoReplacement HTTP status code to return to client
customizedErrorCodestringNoCustom error code string
customizedMessagestringNoCustom error message text
Note: All fields are optional. Only provided fields are updated.

​
Response

​
Success Response (200 OK)

{
  "success": true
}

​
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."
      }
    ]
  }'

​
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

​
Permissions

User must have API_MANAGEMENT + MANAGE permission in the project.