feat(ai-proxy): add UnauthorizedError/TooManyRequestsError and typed AI provider errors

[Scra3]

Summary

• Add UnauthorizedError (401) and TooManyRequestsError (429) to agent-toolkit, re-exported from datasource-toolkit
• Add httpCode property to BusinessError and all subclasses
• Add corresponding cases in the agent's error-handling middleware
• Create typed AI provider errors in ai-proxy:
  • AIProviderError — generic provider error (builds message from cause)
  • AITooManyRequestsError — wraps 429 from providers
  • AIUnauthorizedError — wraps 401 from providers
• Refactor wrapProviderError to use typed errors instead of generic AIUnprocessableError
• Add hierarchy tests for new error classes

[qltysh]

3 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with many returns (count = 9): getErrorStatus	2
qlty	Structure	Function with many parameters (count = 4): constructor	1

[qltysh]

Coverage Impact

⬆️ Merging this pull request will increase total coverage on main by 0.01%.

Modified Files with Diff Coverage (6)

Rating	File	% Diff	Uncovered Line #s
	packages/ai-proxy/src/provider-dispatcher.ts	93.3%	159
	packages/ai-proxy/src/errors.ts	100.0%
	packages/datasource-toolkit/src/errors.ts	100.0%
	packages/agent/src/routes/system/error-handling.ts	100.0%
	packages/agent-toolkit/src/errors.ts	100.0%
	packages/agent/src/types.ts	100.0%
	Total	98.5%

🤖 Increase coverage with AI coding...

In the `feat/add-unauthorized-toomany-errors` branch, add test coverage for this new code:

- `packages/ai-proxy/src/provider-dispatcher.ts` -- Line 159

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

[Scra3]

Impact on forestadmin-server — AI error translator binding

The file packages/private-api/src/domain/ai/error-translator-http.ts needs to be updated to use the new AI error types.

Current (broken after this PR)

import {
  AIError,               // ❌ removed
  AIToolNotFoundError,
  AIUnprocessableError,  // ❌ removed
  McpConfigError,
  McpConflictError,
  McpConnectionError,
} from '@forestadmin/ai-proxy';

After

import {
  AIForbiddenError,         // new (403)
  AIProviderError,          // replaces AIUnprocessableError (422)
  AITooManyRequestsError,   // new (429)
  AIToolNotFoundError,      // unchanged (404)
  AIUnauthorizedError,      // new (401)
  McpConfigError,           // unchanged (422)
  McpConflictError,         // unchanged (409)
  McpConnectionError,       // unchanged (424)
} from '@forestadmin/ai-proxy';

import {
  ConflictError,
  FailedDependencyError,
  ForbiddenError,
  NotFoundError,
  UnauthorizedError,
  UnprocessableEntityError,
} from '../../utils/errors/common-errors';

Updated switch

export default function aiErrorTranslator(error: unknown) {
  if (!error || !(error instanceof Error)) return error;

  switch (true) {
    case error instanceof AITooManyRequestsError:
      return new UnprocessableEntityError('AI rate limit', `AI: ${error.message}`);
      // Note: server TooManyRequestError requires retryAfter which we don't have
    case error instanceof AIUnauthorizedError:
      return new UnauthorizedError(`AI: ${error.message}`);
    case error instanceof AIForbiddenError:
      return new ForbiddenError(`AI: ${error.message}`);
    case error instanceof AIProviderError:
      return new UnprocessableEntityError('AI command', `AI: ${error.message}`);
    case error instanceof AIToolNotFoundError:
      return new NotFoundError(`AI: ${error.message}`);
    case error instanceof McpConnectionError:
      return new FailedDependencyError('MCP Connection Error', null, error);
    case error instanceof McpConfigError:
      return new UnprocessableEntityError('MCP config', `MCP Config Error: ${error.message}`);
    case error instanceof McpConflictError:
      return new ConflictError('MCP config', `MCP Config Error: ${error.message}`);
    default:
      return error;
  }
}

Key changes

• AIError and AIUnprocessableError no longer exist → replaced by AIProviderError
• 3 new error types: AITooManyRequestsError (429), AIUnauthorizedError (401), AIForbiddenError (403)
• The AIError catch-all (→ InternalServerError) is removed — each AI error now maps to its dedicated HTTP type
• AITooManyRequestsError mapped to UnprocessableEntityError for now because server's TooManyRequestError requires a retryAfter value we don't have from the provider