fix(providers): detect gateway missing Messages API and surface actionable error (#158)

Third-party Anthropic relays (sub2api, claude2api, anyrouter…) often
implement GET /v1/models but stub POST /v1/messages with "not
implemented" / 501. The connection test passes but real generation
fails. Previously this was treated as a retryable 5xx — users waited
three rounds of exponential backoff only to see a generic "check your
API key" message that points them in the wrong direction.

- Add looksLikeGatewayMissingMessagesApi in @open-codesign/providers
- Short-circuit retry.ts on 5xx + not-implemented bodies
- Tag the error with new PROVIDER_GATEWAY_INCOMPATIBLE code in core's
  remapProviderError so the UI surfaces an actionable message (switch
  wire to openai-chat, or use a gateway that supports the Messages API)
- Locale entries for en and zh-CN

Signed-off-by: hqhq1025 <1506751656@qq.com>

Author: hqhq1025

packages/core/src/errors.test.ts

@@ -83,6 +83,20 @@ describe('remapProviderError', () => {
     expect(out).toBe(err);
   });
 
+  it('tags 5xx "not implemented" bodies as PROVIDER_GATEWAY_INCOMPATIBLE', () => {
+    const err = httpError(500, 'not implemented');
+    const out = remapProviderError(err, 'anthropic');
+    expect(out).toBeInstanceOf(CodesignError);
+    expect((out as CodesignError).code).toBe('PROVIDER_GATEWAY_INCOMPATIBLE');
+    expect((out as CodesignError).message).toContain('not implemented');
+  });
+
+  it('tags status-less errors whose message mentions 501 as PROVIDER_GATEWAY_INCOMPATIBLE', () => {
+    const out = remapProviderError(new Error('HTTP 501 from gateway'), 'anthropic');
+    expect(out).toBeInstanceOf(CodesignError);
+    expect((out as CodesignError).code).toBe('PROVIDER_GATEWAY_INCOMPATIBLE');
+  });
+
   it('extracts status code from CodesignError messages that embed it', () => {
     const err = new CodesignError(
       'HTTP 401 — see https://platform.openai.com/account/api-keys',

packages/core/src/errors.ts

@@ -15,6 +15,7 @@
  * layer logs them with `reason`.
  */
 
+import { looksLikeGatewayMissingMessagesApi } from '@open-codesign/providers';
 import type { ProviderId } from '@open-codesign/shared';
 import { CodesignError, ERROR_CODES } from '@open-codesign/shared';
 
@@ -101,6 +102,18 @@ export function rewriteUpstreamMessage(
 export function remapProviderError(err: unknown, provider: string | undefined): unknown {
   if (!(err instanceof Error)) return err;
   if (err instanceof CodesignError && err.code === ERROR_CODES.PROVIDER_ABORTED) return err;
+  // Third-party Anthropic relays often reply to POST /v1/messages with 5xx +
+  // "not implemented" while their /v1/models endpoint works. Catch that shape
+  // before any other classification so the UI can suggest switching wire
+  // instead of the misleading default "check your API key" message.
+  if (
+    !(err instanceof CodesignError && err.code === ERROR_CODES.PROVIDER_GATEWAY_INCOMPATIBLE) &&
+    looksLikeGatewayMissingMessagesApi(err)
+  ) {
+    return new CodesignError(err.message, ERROR_CODES.PROVIDER_GATEWAY_INCOMPATIBLE, {
+      cause: err,
+    });
+  }
   const status = statusFromError(err);
   if (status === undefined || status < 400 || status >= 500) return err;
   const { message, rewritten } = rewriteUpstreamMessage(err.message, provider, status);

packages/i18n/src/locales/en.json

@@ -1030,6 +1030,7 @@
     "PROVIDER_ERROR": "The provider returned an error. Check your API key and try again.",
     "PROVIDER_HTTP_4XX": "The provider rejected the request. Verify your API key and billing.",
     "PROVIDER_UPSTREAM_ERROR": "The provider returned an unexpected error. Details are in the log.",
+    "PROVIDER_GATEWAY_INCOMPATIBLE": "Your gateway returned 'not implemented' for the Messages API. Try switching wire to openai-chat in Settings, or use a gateway that supports the Anthropic Messages API.",
     "PROVIDER_ABORTED": "Generation was cancelled.",
     "PROVIDER_RETRY_EXHAUSTED": "The provider failed after several retries. Check your connection and try again.",
     "CLAUDE_CODE_OAUTH_ONLY": "Your Claude Code login uses an Anthropic subscription (Pro/Max). Third-party apps cannot reuse the subscription quota — generate an API key at console.anthropic.com and use it here.",

packages/i18n/src/locales/zh-CN.json

@@ -1026,6 +1026,7 @@
     "PROVIDER_ERROR": "provider 返回错误，请检查 API key 后重试。",
     "PROVIDER_HTTP_4XX": "provider 拒绝请求，请检查 API key 和账户余额。",
     "PROVIDER_UPSTREAM_ERROR": "provider 返回未知错误，详情见日志。",
+    "PROVIDER_GATEWAY_INCOMPATIBLE": "网关对 Messages API 返回 “not implemented”。请到设置中把 wire 切换为 openai-chat，或更换支持 Anthropic Messages API 的网关。",
     "PROVIDER_ABORTED": "生成已取消。",
     "PROVIDER_RETRY_EXHAUSTED": "多次重试后 provider 仍然失败，请检查网络后重试。",
     "CLAUDE_CODE_OAUTH_ONLY": "你的 Claude Code 使用的是 Anthropic 订阅（Pro/Max），第三方应用无法复用订阅额度——请到 console.anthropic.com 生成 API key 后填入。",

packages/providers/src/gateway-compat.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { looksLikeGatewayMissingMessagesApi } from './gateway-compat';
+
+describe('looksLikeGatewayMissingMessagesApi', () => {
+  it('matches plain "not implemented"', () => {
+    expect(looksLikeGatewayMissingMessagesApi(new Error('500 not implemented'))).toBe(true);
+  });
+
+  it('matches "Not Implemented" with different case and spacing', () => {
+    expect(looksLikeGatewayMissingMessagesApi(new Error('Not  Implemented'))).toBe(true);
+  });
+
+  it('matches "Messages API not supported"', () => {
+    expect(
+      looksLikeGatewayMissingMessagesApi(new Error('Messages API not supported on this relay')),
+    ).toBe(true);
+  });
+
+  it('matches "unsupported Messages API" phrasing', () => {
+    expect(looksLikeGatewayMissingMessagesApi(new Error('unsupported messages api endpoint'))).toBe(
+      true,
+    );
+  });
+
+  it('matches bare 501 status code in text', () => {
+    expect(looksLikeGatewayMissingMessagesApi(new Error('HTTP 501 from gateway'))).toBe(true);
+  });
+
+  it('ignores ordinary 500 messages that do not mention not-implemented', () => {
+    expect(looksLikeGatewayMissingMessagesApi(new Error('500 internal server error'))).toBe(false);
+  });
+
+  it('handles non-Error inputs safely', () => {
+    expect(looksLikeGatewayMissingMessagesApi(undefined)).toBe(false);
+    expect(looksLikeGatewayMissingMessagesApi(null)).toBe(false);
+    expect(looksLikeGatewayMissingMessagesApi('not implemented')).toBe(true);
+  });
+});

packages/providers/src/gateway-compat.ts

@@ -0,0 +1,27 @@
+/**
+ * Gateway compatibility detection.
+ *
+ * Third-party Anthropic-compatible relays (sub2api, claude2api, anyrouter…)
+ * frequently implement GET /v1/models (which is what our connection test
+ * hits) but stub out POST /v1/messages with "not implemented" / 501. That
+ * combination passes the onboarding check but explodes on the first real
+ * generation. Treating it as a retryable 5xx wastes the user's time with
+ * exponential backoff and surfaces a misleading "check your API key" blurb.
+ *
+ * This helper detects the tell-tale upstream text so both the retry layer
+ * (to short-circuit) and the core error remapper (to tag it with an
+ * actionable code) can react correctly.
+ */
+
+const NOT_IMPLEMENTED_PATTERNS: readonly RegExp[] = [
+  /not\s+implemented/i,
+  /unsupported.*messages?\s*api/i,
+  /messages?\s*api.*not\s*supported/i,
+  /\b501\b/,
+];
+
+export function looksLikeGatewayMissingMessagesApi(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err ?? '');
+  if (!msg) return false;
+  return NOT_IMPLEMENTED_PATTERNS.some((re) => re.test(msg));
+}

packages/providers/src/index.ts

@@ -419,6 +419,8 @@ export type {
   RetryReason,
 } from './retry';
 
+export { looksLikeGatewayMissingMessagesApi } from './gateway-compat';
+
 export { injectSkillsIntoMessages, formatSkillsForPrompt, filterActive } from './skill-injector';
 
 // Tier 2 surface (not yet implemented):

packages/providers/src/retry.test.ts

@@ -24,6 +24,11 @@ describe('classifyError', () => {
   it('marks 5xx as retryable', () => {
     expect(classifyError(new HttpError('boom', 503))).toMatchObject({ retry: true });
   });
+  it('does not retry 5xx when body says Messages API is not implemented', () => {
+    const d = classifyError(new HttpError('500 not implemented', 500));
+    expect(d.retry).toBe(false);
+    expect(d.reason).toMatch(/gateway does not implement Messages API/);
+  });
   it('marks 4xx (non-429) as non-retryable', () => {
     expect(classifyError(new HttpError('bad', 400))).toMatchObject({ retry: false });
   });

packages/providers/src/retry.ts

@@ -15,6 +15,7 @@
 
 import { type ChatMessage, CodesignError, ERROR_CODES, type ModelRef } from '@open-codesign/shared';
 import { normalizeProviderError } from './errors';
+import { looksLikeGatewayMissingMessagesApi } from './gateway-compat';
 import { type GenerateOptions, type GenerateResult, complete } from './index';
 
 export interface RetryReason {
@@ -58,6 +59,14 @@ function classifyByStatus(status: number, err: unknown): RetryDecision | undefin
     return decision;
   }
   if (status >= 500 && status <= 599) {
+    // Third-party Anthropic relays (sub2api, claude2api, anyrouter…) often
+    // return 5xx + "not implemented" for POST /v1/messages even though their
+    // /v1/models endpoint works. Retrying wastes 3 rounds of exponential
+    // backoff on an endpoint that will never respond; short-circuit so the
+    // user sees the actionable error immediately.
+    if (looksLikeGatewayMissingMessagesApi(err)) {
+      return { retry: false, reason: 'gateway does not implement Messages API' };
+    }
     return { retry: true, reason: `server error (${status})` };
   }
   if (status >= 400 && status <= 499) {

packages/shared/src/error-codes.ts

@@ -26,6 +26,7 @@ export const ERROR_CODES = {
   PROVIDER_ERROR: 'PROVIDER_ERROR',
   PROVIDER_HTTP_4XX: 'PROVIDER_HTTP_4XX',
   PROVIDER_UPSTREAM_ERROR: 'PROVIDER_UPSTREAM_ERROR',
+  PROVIDER_GATEWAY_INCOMPATIBLE: 'PROVIDER_GATEWAY_INCOMPATIBLE',
   PROVIDER_ABORTED: 'PROVIDER_ABORTED',
   PROVIDER_RETRY_EXHAUSTED: 'PROVIDER_RETRY_EXHAUSTED',
   CLAUDE_CODE_OAUTH_ONLY: 'CLAUDE_CODE_OAUTH_ONLY',
@@ -163,6 +164,13 @@ export const ERROR_CODE_DESCRIPTIONS: Record<CodesignErrorCode, ErrorCodeDescrip
     userFacingKey: 'err.PROVIDER_UPSTREAM_ERROR',
     category: 'provider',
   },
+  PROVIDER_GATEWAY_INCOMPATIBLE: {
+    userFacing:
+      "Your gateway returned 'not implemented' for the Messages API. " +
+      'Try switching wire to openai-chat in Settings, or use a gateway that supports the Anthropic Messages API.',
+    userFacingKey: 'err.PROVIDER_GATEWAY_INCOMPATIBLE',
+    category: 'provider',
+  },
   PROVIDER_ABORTED: {
     userFacing: 'Generation was cancelled.',
     userFacingKey: 'err.PROVIDER_ABORTED',