Create error handler extension point

Freigeben Version: Australia

Aktualisiert 12. März 2026

1 Minute Lesedauer

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

Vorbereitungen

Role required: admin

Warum und wann dieser Vorgang ausgeführt wird

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

Prozedur

Navigate to All > System Extension Points > Scripted Extension Points.
In the API Name field, search and select the BYOMEmbeddingGenerationErrorHandler extension point.
From Related Links, select Create implementation.

On the Script Include form, update the script as required.

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:

var BYOMEmbeddingGenerationErrorHandler = Class.create();
BYOMEmbeddingGenerationErrorHandler.prototype = {
    initialize: function() {},

    process: function(inputParams) {
        var responseStatus = inputParams.responseStatus;
        var responseErrorCode = parseInt(inputParams.responseErrorCode);
        var responseBody = inputParams.responseBody;
        var responseHeaders = inputParams.responseHeaders;
        var responseErrorMessage = inputParams.responseErrorMessage;
        var passages = inputParams.passages;
        var maxTokens = inputParams.maxTokens;
        var additionalParams = {};

        var response = BYOMEmbeddingUtil.buildErrorResponse(
            BYOMEmbeddingUtil.ErrorCodeEnum.UNKNOWN_ERROR,
            "unknown error",
            additionalParams
        );

To categorize errors, use the following BYOMEmbeddingUtil.ErrorCodeEnum codes:

javascript
CopyEdit
BYOMEmbeddingUtil.ErrorCodeEnum = {
    REQUEST_SIZE_TOO_LARGE_ERROR: "RequestSizeTooLargeError",        // Reduce batch size and retry
    RATE_LIMIT_ERROR: "RateLimitError",                              // Retry without reducing batch size
    PASSAGE_SIZE_TOO_LARGE_ERROR: "PassageSizeTooLargeError",        // Retry with reduced passage size
    UNKNOWN_ERROR: "UnknowError",                                     // Ignore this run; retry in next job
    SKIP_BATCH_ERROR: "SkipBatchError",                              // Skip the entire batch, no retry
    UPDATE_PASSAGE_CONTENT_ERROR: "UpdatePassageContentError",       // Retry with updated passage content
    RETRY_SKIP_ON_FAIL_ERROR: "RetrySkipOnFailError"                 // Retry with backoff; skip on failure
};

Allowed Fields for buildErrorResponse includes:

javascript
CopyEdit
var allowedFieldsByErrorCode = {
    REQUEST_SIZE_TOO_LARGE_ERROR: ['error_code', 'error_message'],
    RATE_LIMIT_ERROR: ['error_code', 'error_message', 'retry_after_seconds'],
    PASSAGE_SIZE_TOO_LARGE_ERROR: ['error_code', 'error_message', 'passages'],
    UNKNOWN_ERROR: ['error_code', 'error_message'],
    SKIP_BATCH_ERROR: ['error_code', 'error_message'],
    UPDATE_PASSAGE_CONTENT_ERROR: ['error_code', 'error_message', 'passages'],
    RETRY_SKIP_ON_FAIL_ERROR: ['error_code', 'error_message']
};

Retry Behavior by Error Code includes:


Error Code	Description	Retry Strategy
REQUEST_SIZE_TOO_LARGE_ERROR	Batch too large	Reduces batch size, retries exponentially.
RATE_LIMIT_ERROR	Rate limit reached	Waits for `retry_after_seconds`, then retries.
PASSAGE_SIZE_TOO_LARGE_ERROR	Passage too large	Reduces passage length (usually half), then retries.
UNKNOWN_ERROR	Unknown issue	Skips retry this run, automatically retried in the next scheduled job.
SKIP_BATCH_ERROR	Irrecoverable issue with batch	Skips entire batch without retry.
UPDATE_PASSAGE_CONTENT_ERROR	Retry with corrected content	Uses corrected passages from response and retries.
RETRY_SKIP_ON_FAIL_ERROR	Retry then skip	Retries with exponential back off, marks as failed after max retries.

Select Update.