Error Message Configuration Guide

bilgi

This page provides a centralized explanation of all layers, working principles and priority order of the error message configuration system in Apinizer. All error message customization methods across policies, routing and platform-wide settings are covered here.

Multi-Layered Configuration System

Apinizer allows you to configure error messages at four different levels. Each level can override the level above it. This way, you can define a consistent error behavior across the platform while returning completely different responses for specific policies or error types.

Configuration Levels

Level	Configuration Location	Scope	Purpose
1. Platform-Wide	System Settings > Error Messages	All API Proxies and policies	Define standard error format across the organization
2. API Proxy / Proxy Group	API Proxy Settings	Specific API Proxy or group	Define API-specific error response template (JSON/XML)
3. Policy / Routing	Policy or routing update screen	Specific policy or routing address	Define policy-specific error message and template
4. Per-Error	Error row in policy or platform-wide screen	Specific error type	Customized response for a single error type

ipucu

This multi-layered structure provides the flexibility to handle everything from a simple "show the same message for all errors" requirement to complex "return different responses for different error types based on different conditions" scenarios.

Error Message Priority Order

When an error occurs, the Gateway determines which error response to return based on the following priority order. The response of the first matching level is used; lower levels are not evaluated.

Priority	Source	Description
1 (Highest)	Per-error custom message template	Template-based custom message builder defined for a specific error type in policy, routing or platform-wide settings
2	Policy / routing-level custom message template	Template-based custom message builder defined at policy or routing level (for all error types)
3	Error response rules	Condition-based response rules — return different error responses based on request information (path, header, method, etc.)
4	Per-error field customization	Row-level Customized Message, Customized Error Code, Customized HTTP Status Code fields in policy, routing or platform-wide settings
5	Platform-wide error message customization	Customizations made from System Settings > Error Messages page
6 (Lowest)	Default error message	Default error message defined by the system

uyarı

If a higher-priority source is defined, lower-priority sources are not evaluated. For example, if a custom message template is active for an error row, the policy-level template, error response rules, or row-level field customizations are not considered.

Workflow: How an Error Becomes a Response

Below is a summary of the steps from when an error occurs to when it is returned to the end user:

Step 1: Error Occurs

An error occurs during policy, routing or API Proxy processing (e.g., authentication failed, quota exceeded, schema validation failed, etc.).

Step 2: Default Values Determined

The system determines the default HTTP status code, error code and error message corresponding to the error type.

Step 3: Platform-Wide Customizations Checked

If customized values are defined for this error type in System Settings > Error Messages, they override the default values.

Step 4: Policy/Routing Level Customization

If customization is defined for this error type in the policy or routing configuration that threw the error, it is applied. In order:

1. Per-error custom message template is checked (highest priority)
2. Policy/routing-level custom message template is checked
3. Error response rules are evaluated in order
4. Row-level field customization is applied

Step 5: Error Response Template Applied

If a JSON or XML error response template is defined at the API Proxy or Proxy Group level, placeholders are resolved and the response body is created. If no template exists, the default format is used.

Step 6: Response Sent to Client

The generated error response is sent to the client with the specified HTTP status code and content type.

Configuration Methods

1. Field-Based Customization (Simple)

You can customize the HTTP status code, error code and error message fields for each error row. This method ensures that a specific error is returned with a fixed message.

Configuration locations:

• System Settings > Error Messages (platform-wide)
• Policy update screen > Error Message Customization tab (policy-level)
• Routing update screen > Error Messages section (routing-level)

2. Template-Based Custom Message Builder (Dynamic)

By writing a free-text template, you can automatically include request and error information in the response using placeholders. This method allows you to create dynamic error responses that contain different information for each request.

Two usage modes:

• Per-error: Custom template for a specific error type (highest priority)
• Policy/routing-wide: Single template for all error types

Configuration fields:

Field	Description
Message Template	Free-text template. Placeholders can be used
Content-Type	Response content type (default: application/json;charset=utf-8)
HTTP Status Code	HTTP status code to return when this error occurs

3. Error Response Rules (Conditional)

By defining condition-based response rules, you can return different error responses based on request information (path, header, HTTP method, etc.).

How rules work:

1. When an error occurs, defined rules are evaluated in order number sequence
2. The template of the first matching rule is applied
3. If no rule matches, the next priority level is used
4. A rule without a condition acts as a default rule (catch-all) and always matches

uyarı

If the custom message builder is active for the same error row, error response rules are not evaluated. The custom message builder has higher priority.

Fields defined in each rule:

Field	Description
Order	Rule evaluation order (lower number = higher priority)
Name	Rule identifier name
Condition	Match condition based on request information. If left empty, the rule works unconditionally (catch-all)
Message Template	Template that creates the error response body
Content-Type	Response content type
HTTP Status Code	Response HTTP status code
Active	Rule active/inactive status

4. API Proxy Error Response Template

JSON and XML format error response templates can be defined at the API Proxy or Proxy Group level. These templates are used as the default error response format when no customization is made with the above methods.

Configuration location: API Proxy Settings or API Proxy Group settings

The appropriate template (JSON or XML) is automatically selected based on the request content type.

Placeholders and Variables

Placeholders that can be used in template-based messages and error response rules:

Standard Placeholders

Used in API Proxy error response templates and error response rules:

Placeholder	Description
#CORRELATIONID#	Request tracking number
#FAULTCODE#	Error code
#FAULTMESSAGE#	Error message
#FAULTMESSAGE_FIRSTLINE#	First line of error message
#FAULTSTATUSCODE#	HTTP status code
#RESPONSEFROMAPI#	Backend API response (if available)
#RESPONSEFROMAPI_FIRSTLINE#	First line of backend API response

Error Variables

Used in template-based messages and error response rules:

Variable	Description
#{error.customizedErrorCode}	Customized error code
#{error.customizedHttpCode}	Customized HTTP status code
#{error.customizedMessage}	Customized error message
#{error.defaultErrorCode}	Default error code
#{error.defaultMessage}	Default error message
#{error.defaultHttpCode}	Default HTTP status code

Request Variables

Variable	Description
#{request.method}	HTTP method (GET, POST, etc.)
#{request.uri}	Request URI
#{request.contentType}	Request content type
#{request.remoteAddress}	Client IP address
#{request.queryString}	Query parameters
#{request.pathInfo}	Request path
#{request.contextPath}	Context path

Message and API Variables

Variable	Description
#{message.correlationId}	Request tracking number (correlation ID)
#{apiProxy.id}	API Proxy identifier
#{apiProxy.name}	API Proxy name

Date/Time Variables

Variable	Description
#{dateTime.year}	Year
#{dateTime.month}	Month
#{dateTime.dayOfMonth}	Day of month
#{dateTime.hour}	Hour
#{dateTime.minute}	Minute
#{dateTime.second}	Second
#{dateTime.timestamp}	Unix timestamp
#{dateTime.formattedText}	Formatted date/time

Environment Variables

Environment variables can be used in ${VARIABLE_NAME} format. For detailed information about environment variables, see the Environment Variables page.

Scenario Examples

Scenario 1: Standard JSON Format for All Errors

If you want all API errors to return in the same JSON format across the organization, field-based customization at the platform level is sufficient.

Configuration location: System Settings > Error Messages

Edit the customized message, error code, and HTTP status code fields on each error row. All API Proxies will automatically use these values.

Scenario 2: Different Error Message for a Specific Policy

If you want to return a custom message for the "User not found" error in an authentication policy:

Configuration location: Policy update screen > Error Message Customization tab

Edit the customized message field on the relevant error row. This will only apply to errors thrown from this policy.

Scenario 3: Dynamic Error Response (Template-Based)

If you want to return a detailed response containing request information and tracking number for every error, use the template-based custom message builder.

Configuration location: Policy update screen > Error Message Customization tab > relevant error row > Customize button

Example template:

{
  "error": {
    "code": "#{error.defaultErrorCode}",
    "message": "#{error.defaultMessage}",
    "timestamp": "#{dateTime.formattedText}",
    "correlationId": "#{message.correlationId}",
    "path": "#{request.uri}"
  }
}

Example response:

{
  "error": {
    "code": "ERR-035",
    "message": "Authentication policy failed! Invalid API Key/Username and Password pair for Authenticator (SecretManager)!",
    "timestamp": "2026-04-05 14:30:45",
    "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "path": "/api/v1/users"
  }
}

Scenario 4: Different Error Format Based on Client Type (Conditional Response Rules)

If you want to return short messages to mobile clients and detailed messages to web clients for the same error type, use error response rules.

Configuration location: Policy update screen or System Settings > Error Messages > relevant error row > Customize button

Rule 1 (Order: 1, Condition: Header X-Client-Type = mobile):

{
  "code": "#{error.defaultErrorCode}",
  "message": "Request failed"
}

Rule 2 (Order: 2, No condition — catch-all):

{
  "error": {
    "code": "#{error.defaultErrorCode}",
    "message": "#{error.defaultMessage}",
    "correlationId": "#{message.correlationId}",
    "timestamp": "#{dateTime.formattedText}",
    "path": "#{request.uri}",
    "method": "#{request.method}"
  }
}

In this configuration, mobile clients receive a short response while all other clients receive a detailed response.

Scenario 5: Custom Message in Business Rule STOP Action

If you want to return a custom error message when stopping the flow with the STOP action in a Business Rule policy:

Configuration location: Business Rule policy update screen > Error Message Customization tab

Enable the policy-wide custom message template and write the template:

Your API call was rejected by a business rule.
Error Code: #{error.defaultErrorCode}
Time: #{dateTime.formattedText}
Request ID: #{message.correlationId}

What Makes This System Dynamic?

Apinizer's error message configuration system provides an extremely flexible and dynamic solution for the following reasons:

• Layered override: Each level can override the level above it. You can define a standard behavior platform-wide and define exceptions for specific APIs or policies.
• Condition-based response rules: You can return completely different responses for the same error type based on request information (header, path, method, IP, etc.).
• Dynamic placeholders: By using request information, error information, time information and environment variables in templates, you can create different content for each request.
• Three format support: You can define error responses in JSON, XML and plain text formats; automatic format selection based on request content type.
• Centralized and distributed management: You can manage all errors at once from the platform level or make independent configurations at the policy/routing level.

Related Pages

Error Messages (System Settings)

Platform-wide error message management, all error types table

What is Policy?

Policy-level error message customization

API Proxy Settings

JSON/XML error response template configuration

HTTP Routing

Routing-level error message customization

Dynamic Variables

All variables available in templates

Business Rule

Custom error message usage in STOP action