opencode-rate-limit

OpenCode plugin for proactive TPM/RPM rate limiting with multi-provider fallback.

Features

• Proactive TPM/RPM limiting — counts tokens per minute, blocks requests before they hit the API
• Reactive error detection — parses response body against user-configured regex rules
• Fuzzy error matching — bodyPattern regex matches any text in the response body
• Multi-provider support — different error rules per provider
• Fallback model switching — auto-switch to backup models when rate limited
• Circuit breaker — auto-disconnect failing models
• Smart cooldown — skip rate-limited models for configurable duration
• /rate-limit-status — diagnostic command

Install

Add to opencode.json:

{
  "plugin": ["opencode-rate-limit"]
}

Configure

Create ~/.opencode/rate-limit.json:

{
  "providers": [
    {
      "provider": "xfyun",
      "tpm": 100000,
      "rpm": 10,
      "errorDetection": [
        { "bodyPattern": "11210|TPM.*超限", "category": "tpm", "description": "TPM超限", "waitMs": 60000 },
        { "bodyPattern": "11201|次数超限", "category": "tpm", "description": "次数超限", "waitMs": 60000 },
        { "statusPattern": "^429$", "category": "tpm", "description": "HTTP 429", "waitMs": 60000 },
        { "statusPattern": "^5\\d{2}$", "category": "server_error", "description": "HTTP 5xx" },
        { "statusPattern": "^401$", "category": "fatal", "description": "HTTP 401" }
      ]
    }
  ],
  "fallbackModels": [
    { "providerId": "openai", "modelId": "gpt-4o" }
  ]
}

Error categories

| Category | Behavior | |----------|----------| | tpm | Wait waitMs (default 60s), then retry or fallback | | rpm | Wait waitMs, then retry or fallback | | server_error | Wait cooldownMs, retry with backoff | | retryable | Wait waitMs, retry | | fatal | No retry, propagate error immediately |

Pattern matching

• statusPattern — regex against HTTP status code string (e.g. "^429$", "^5\\d{2}$")
• bodyPattern — regex against full response body (case-insensitive, fuzzy match)
• Both optional — at least one required per rule
• When both specified, BOTH must match (AND logic)
• Rules checked in order, first match wins

Full config reference

{
  "enabled": true,
  "cooldownMs": 60000,
  "fallbackMode": "cycle",
  "fallbackModels": [],
  "retryPolicy": {
    "maxRetries": 3,
    "strategy": "exponential",
    "baseDelayMs": 1000,
    "maxDelayMs": 30000,
    "jitterEnabled": true
  },
  "circuitBreaker": {
    "enabled": true,
    "failureThreshold": 5,
    "recoveryTimeoutMs": 60000
  },
  "providers": [],
  "fetchInterception": true,
  "eventFallback": true,
  "logLevel": "warn"
}

Preset templates

Copy from src/error-codes.ts:

• XUNFEI_PRESET — 讯飞星辰 MaaS Astron Coding Plan
• OPENAI_PRESET — Standard OpenAI-compatible providers

License

MIT