diff --git a/en/docs/reference/config-catalog.md b/en/docs/reference/config-catalog.md index d731ac0cd0..2d7b9f3fc1 100644 --- a/en/docs/reference/config-catalog.md +++ b/en/docs/reference/config-catalog.md @@ -3165,6 +3165,7 @@ enable = true token = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" endpoint = "https://e95488c8-8511-4882-967f-ec3ae2a0f86f-prod.e1-us-east-azure.choreoapis.dev/lgpt/interceptor-service/interceptor-service-be2/v1.0" default_request_timeout = 30 +custom_error_response_sequence = "openai_error_response_formatter" [apim.ai.failover_configurations] failover_endpoints_limit = 10 @@ -3259,6 +3260,27 @@ default_request_timeout = 30

The default timeout (in seconds) for AI API requests

+
+
+ custom_error_response_sequence +
+
+
+

+ string + +

+
+ Default: +
+
+ Possible Values: openai_error_response_formatter +
+
+
+

The name of the Synapse sequence used to format gateway error responses for AI APIs. Applies only to AI APIs. If not set, AI APIs use the default error response format.

+
+
[apim.ai.failover_configurations] diff --git a/en/docs/reference/troubleshooting/error-handling.md b/en/docs/reference/troubleshooting/error-handling.md index 336908ca8b..6c3b72a23b 100644 --- a/en/docs/reference/troubleshooting/error-handling.md +++ b/en/docs/reference/troubleshooting/error-handling.md @@ -446,3 +446,49 @@ message's HTTP status code as a custom error message: {"fault":{"code":900901,"type":"Status report","message":"Runtime Error","description":"Invalid Credentials"}} ``` +## Customize Error Responses for AI APIs + +To enable custom error response formatting for AI APIs, add the following configuration to the `/repository/conf/deployment.toml` file. For more information, see the [Configuration Catalog]({{base_path}}/reference/config-catalog/). + +```toml +[apim.ai] +custom_error_response_sequence = "openai_error_response_formatter" +``` + +!!! info + + In a distributed deployment, add this configuration to the `deployment.toml` file of both the **API Control Plane (ACP)** node (`/repository/conf/deployment.toml`) and the **Universal Gateway** node (`/repository/conf/deployment.toml`). + +When this configuration is enabled, gateway error responses for AI APIs are formatted using the `/repository/deployment/server/synapse-configs/default/sequences/openai_error_response_formatter.xml` Synapse sequence: + +By default, this sequence produces the following OpenAI-compatible error response: + +```json +{ + "error": { + "code": "", + "type": "", + "message": "" + } +} +``` + +To customize the error response format, modify the `openai_error_response_formatter.xml` sequence. + +!!! note + + This configuration applies only to AI APIs. Non-AI APIs, and AI APIs when `custom_error_response_sequence` is not configured, continue to use the default error response format. + +!!! info + + This configuration is available in wso2am-4.6.0 starting from update level 39 and wso2am-universal-gw-4.6.0 starting from update level 38. + +!!! info + + For the customization to take effect on **tenants that existed before this update was applied**, copy the following files from the `/repository/resources/apim-synapse-config` directory to the `/repository/tenants//synapse-configs/default/sequences` directory: + + - `_sandbox_key_error_.xml` + - `guardrail_fault.xml` + + Tenants created after applying this update receive these files automatically during tenant creation. Therefore, no manual copying is required. + diff --git a/en/tools/config-catalog-generator/data/apim.ai.toml b/en/tools/config-catalog-generator/data/apim.ai.toml index 88c3e2e241..140b2b0a76 100644 --- a/en/tools/config-catalog-generator/data/apim.ai.toml +++ b/en/tools/config-catalog-generator/data/apim.ai.toml @@ -3,6 +3,7 @@ enable = true token = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" endpoint = "https://e95488c8-8511-4882-967f-ec3ae2a0f86f-prod.e1-us-east-azure.choreoapis.dev/lgpt/interceptor-service/interceptor-service-be2/v1.0" default_request_timeout = 30 +custom_error_response_sequence = "openai_error_response_formatter" [apim.ai.failover_configurations] failover_endpoints_limit = 10 diff --git a/en/tools/config-catalog-generator/data/configs.json b/en/tools/config-catalog-generator/data/configs.json index f5f887d76e..3c02d5380a 100755 --- a/en/tools/config-catalog-generator/data/configs.json +++ b/en/tools/config-catalog-generator/data/configs.json @@ -1212,6 +1212,14 @@ "default": "30", "possible": "", "description": "The default timeout (in seconds) for AI API requests" + }, + { + "name": "custom_error_response_sequence", + "type": "string", + "required": false, + "default": "", + "possible": "openai_error_response_formatter", + "description": "The name of the Synapse sequence used to format gateway error responses for AI APIs. Applies only to AI APIs. If not set, AI APIs use the default error response format." } ] },