模型发现与 discovery 权限

v0.9.0 起，应用可以查询当前 Gateway Key 所属 Project 允许使用、且当前路由表实际提供的公开别名。这是 Halro 的本地配置查询，不调用上游、不写 Ledger，也不返回 Provider 的账号或模型标识。

权限与请求

Key 必须同时有 inference 和 discovery Scope。旧 Key、未指定 Scope 的 Key，以及 halro key create 签发的 Key 默认只有 inference；缺少发现权限返回 403 gateway_key_scope_denied。请管理员通过 Console 的 Key 对话框或 Admin API 显式授予所需 Scope。

以下 $HALRO_GATEWAY_KEY 应通过安全方式注入；将示例域名和 chat 替换为自己的入口与公开别名。

curl -fsS https://halro.example.com/v1/models \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY"
curl -fsS https://halro.example.com/v1/models/chat \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY"

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://halro.example.com/v1",
    api_key=os.environ["HALRO_GATEWAY_KEY"],
    max_retries=0,
)
for model in client.models.list().data:
    print(model.id)

响应字段与边界

{
  "object": "list",
  "data": [{"id": "chat", "object": "model", "created": 0, "owned_by": "halro"}]
}

响应字段与边界
字段或行为	含义
`id`	公开别名；管理员可更换其背后 Deployment，别名保持不变
`created`	固定 `0`；不伪造别名的创建时间
`owned_by`	固定 `halro`；不泄露上游身份
列表顺序	按别名排序并去重；可能返回空列表
单个别名查询	无权访问和不存在都返回 `404 model_not_found`
查询参数	当前不建模，忽略额外查询参数；没有分页协议

列出来不表示任意请求都能成功。 别名可能只支持另一种 operation，使用时返回 400 unsupported_feature；所有目标不健康或被暂停时仍可能列出，调用返回 503。路由表本身已剔除的别名（例如 capability drift 或不可用出站代理导致目标被移除）不会列出。模型发现不提供 capabilities，不能拿列表替代模型能力核对。

限流与故障处理

发现接口受固定的每 Key 600 次/分钟、每 Project 5,000 次/分钟上限保护，超限返回 429 rate_limit_exceeded 和 Retry-After。这不同于计费推理的 Project RPM/TPM，不能通过配置关闭。固定限制也用于 Files、Batches、Async 与延迟 Responses 资源面；真正调用上游的操作仍受 Project 准入限制。

503 configuration_stale 表示持久化配置尚未安全激活，发现接口也会被拒绝。403 需要修复 Scope， 404 需要核对别名授权与路由，429 应按等待时间退避；不要把它们都解释为 Provider 不可用。见认证与错误。