Introduction

When developing or deploying with DeepSeek Harness Web, error handling is a critical component of service stability. DSH includes a built-in llm-retry mechanism, but error classification often depends on the error code returned by the service. If some rate-limit errors are marked as PI_AI_ERROR instead of RATE_LIMIT, the retry mechanism may not take effect.

The dsh-better-retry plugin solves this problem. By reclassifying specific PI_AI_ERROR values as RATE_LIMIT and working with DSH’s standard retry policy, it lets developers more precisely control which errors are worth retrying and how those errors are matched.

What It Is

This is an error-classification and automatic-retry rule management plugin for DeepSeek Harness Web.

  • Maintainer: leolee9086
  • Core capability: Recognizes specific error message patterns (such as PI_AI_ERROR) and reclassifies them as RATE_LIMIT, allowing them to be handled by DSH’s @deepseek-ai/dsh-llm-retry.
  • Value: Reduces the barrier to configuring retries through normalized message matching and visual rule management, helping avoid request failures caused by improper error classification.

Core Features

Error Reclassification

At runtime, the plugin intercepts PI_AI_ERROR and classifies it as RATE_LIMIT based on configured rules. DSH then decides whether to retry based on its built-in exponential backoff strategy, including jitter. Parameters such as retry count and delay are determined by the provider’s DSH policy, while the original request and diagnostic information remain unchanged.

Two Message Matching Modes

  • Normalized exact matching (default): Removes request, trace, correlation id, and UUIDs, and normalizes case and whitespace. This mode requires the message to match exactly after removing volatile fields, and is suitable for clear, short messages.
  • Contains a contiguous fragment: Supports broader matching. The fragment must be a contiguous text sequence present in the error message and must contain at least 24 characters and 3 whitespace-separated words.

Management Entry Points

The plugin provides two visible management entry points in the Web interface:
1. Settings → Automatic Retry: View all built-in and custom patterns, enable/disable, delete, and add patterns, and test message matching.
2. Error line → Add to Automatic Retry: While browsing error logs, expand the preview form directly to quickly add the current error to automatic retry rules.

Smart Suggestions and Legacy Migration

  • Similar sample suggestions: The plugin analyzes samples from the 100 most recent error types and saved patterns, filters by error code and provider, and suggests common contiguous fragments as matching rules.
  • Legacy migration: Supports migrating from the legacy rules: string[] to the new patterns format.

Installation and Activation

Before installing, ensure that your DSH Web profile includes the llm, settings, connection, and standard llm-retry modules. It also requires support for newer DSH interfaces (connection.rpc.handle/call and settings.section).

Use the official command to install:

dsh plugin --profile web add github:leolee9086/dsh-better-retry

To pin a specific version, append the commit SHA to the command:

dsh plugin --profile web add github:leolee9086/dsh-better-retry#COMMIT_SHA

After installation, refresh the Web page. Use dsh --profile web --dump-config to verify that the configuration includes both llm-retry and dsh-better-retry, and open the management page to confirm that the Host can return the rule list.

Typical Usage

Add an Error to Automatic Retry

  1. In the error log, click “Add to Automatic Retry”.
  2. In the expanded form, “Normalized exact matching” is used by default. Enter the provider ID (* is the default, meaning all providers).
  3. Click “Preview match” to check the normalized message and the matched pattern.
  4. Click “Confirm Add to Automatic Retry”. A successful save is displayed only when the Host persists the rule successfully.

Test Matching

In the “Test whether a message matches” feature on the management page, paste the message text. The Host uses the same matcher as real stream processing to display the currently matched enabled pattern(s), which helps debug rule configuration.

Built-in Patterns

The plugin enables two built-in patterns for common rate-limit errors by default:
* Too many pending requests, please retry later
* Our servers are currently overloaded. Please try again later

Applicable Scenarios and Notes

Applicable Scenarios

Use this when specific error codes (such as PI_AI_ERROR) require fine-grained handling, especially when provider error messages contain many dynamic IDs or unstable formatting but the underlying error meaning is clear.

Notes

  1. Does not resume finished turns: Saving a rule only affects subsequent requests. For conversations that have already ended, no automatic retry occurs even if the rule matches.
  2. Permissions and versions: The plugin runs with the current DSH process permissions. If the management page errors or returns 404, the Host and Client versions are often out of sync; reload the Host plugin rather than only refreshing the browser.
  3. Retry policy: Actual retry behavior is determined by DSH parameters such as maxRetries and backoff. If the provider disables retries or the retry count is exhausted, a matched pattern will not retry indefinitely.
  4. License: The project is licensed under the MIT License and can be used and modified freely.

Summary

dsh-better-retry provides a visual, message-pattern-based error-classification tool. It does not replace DSH’s retry engine; instead, it acts as a “translator” that converts hard-to-identify errors into retryable errors. Through normalized matching and an intuitive management interface, it reduces the complexity of error handling.

  • Project directory: https://www.skillhub.cn/plugins/leolee9086/dsh-better-retry
  • GitHub repository: https://github.com/leolee9086/dsh-better-retry