{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":38191,"path":"platform-administration/ai-search/create-error-handler-extention-point.md","title":"Create error handler extension point","bundle":null,"doc_type":null,"release":"australia","body":"\n# Create error handler extension point\n\nCreate a scripted extension point to handle embedding generation errors that occur when custom embedding models generate semantic vectors. Using extension point enables you to create a primary ticket type as per the extension point definition.\n\n## Before you begin\n\nRole required: admin\n\n## About this task\n\nThe `BYOMEmbeddingGenerationErrorHandler` script enables you to control retry logic, batch failure handling, and passage modification during embedding generation. These flexible strategies improve the robustness of large-scale semantic indexing pipelines.\n\n## Procedure\n\n1.  Navigate to **All** > **System Extension Points** > **Scripted Extension Points**.\n\n2.  In the **API Name** field, search and select the **BYOMEmbeddingGenerationErrorHandler** extension point.\n\n3.  From Related Links, select **Create implementation**.\n\n4.  On the Script Include form, update the script as required.\n\n    1.  To handle the embedding generation errors by a custom embedding model, defines a process\\(inputParams\\) method in the extension point script. This method must return a structured response based on predefined error categories:\n\n        ```\n        var BYOMEmbeddingGenerationErrorHandler = Class.create();\n        BYOMEmbeddingGenerationErrorHandler.prototype = {\n            initialize: function() {},\n        \n            process: function(inputParams) {\n                var responseStatus = inputParams.responseStatus;\n                var responseErrorCode = parseInt(inputParams.responseErrorCode);\n                var responseBody = inputParams.responseBody;\n                var responseHeaders = inputParams.responseHeaders;\n                var responseErrorMessage = inputParams.responseErrorMessage;\n                var passages = inputParams.passages;\n                var maxTokens = inputParams.maxTokens;\n                var additionalParams = {};\n        \n                var response = BYOMEmbeddingUtil.buildErrorResponse(\n                    BYOMEmbeddingUtil.ErrorCodeEnum.UNKNOWN_ERROR,\n                    \"unknown error\",\n                    additionalParams\n                );\n        \n        ```\n\n    2.  To categorize errors, use the following `BYOMEmbeddingUtil.ErrorCodeEnum` codes:\n\n        ```\n        BYOMEmbeddingUtil.ErrorCodeEnum = {\n            REQUEST_SIZE_TOO_LARGE_ERROR: \"RequestSizeTooLargeError\",        // Reduce batch size and retry\n            RATE_LIMIT_ERROR: \"RateLimitError\",                              // Retry without reducing batch size\n            PASSAGE_SIZE_TOO_LARGE_ERROR: \"PassageSizeTooLargeError\",        // Retry with reduced passage size\n            UNKNOWN_ERROR: \"UnknowError\",                                     // Ignore this run; retry in next job\n            SKIP_BATCH_ERROR: \"SkipBatchError\",                              // Skip the entire batch, no retry\n            UPDATE_PASSAGE_CONTENT_ERROR: \"UpdatePassageContentError\",       // Retry with updated passage content\n            RETRY_SKIP_ON_FAIL_ERROR: \"RetrySkipOnFailError\"                 // Retry with backoff; skip on failure\n        };\n        \n        ```\n\n    3.  Allowed Fields for `buildErrorResponse` includes:\n\n        ```\n        var allowedFieldsByErrorCode = {\n            REQUEST_SIZE_TOO_LARGE_ERROR: ['error_code', 'error_message'],\n            RATE_LIMIT_ERROR: ['error_code', 'error_message', 'retry_after_seconds'],\n            PASSAGE_SIZE_TOO_LARGE_ERROR: ['error_code', 'error_message', 'passages'],\n            UNKNOWN_ERROR: ['error_code', 'error_message'],\n            SKIP_BATCH_ERROR: ['error_code', 'error_message'],\n            UPDATE_PASSAGE_CONTENT_ERROR: ['error_code', 'error_message', 'passages'],\n            RETRY_SKIP_ON_FAIL_ERROR: ['error_code', 'error_message']\n        };\n        \n        ```\n\n    4.  Retry Behavior by Error Code includes:\n\n        |Error Code|Description|Retry Strategy|\n        |----------|-----------|--------------|\n        |REQUEST\\_SIZE\\_TOO\\_LARGE\\_ERROR|Batch too large|Reduces batch size, retries exponentially.|\n        |RATE\\_LIMIT\\_ERROR|Rate limit reached|Waits for `retry_after_seconds`, then retries.|\n        |PASSAGE\\_SIZE\\_TOO\\_LARGE\\_ERROR|Passage too large|Reduces passage length \\(usually half\\), then retries.|\n        |UNKNOWN\\_ERROR|Unknown issue|Skips retry this run, automatically retried in the next scheduled job.|\n        |SKIP\\_BATCH\\_ERROR|Irrecoverable issue with batch|Skips entire batch without retry.|\n        |UPDATE\\_PASSAGE\\_CONTENT\\_ERROR|Retry with corrected content|Uses corrected passages from response and retries.|\n        |RETRY\\_SKIP\\_ON\\_FAIL\\_ERROR|Retry then skip|Retries with exponential back off, marks as failed after max retries.|\n\n5.  Select **Update**.\n\n\n"}}