身份验证的工作方式
向 Sorsa API 发送的每个请求都必须在ApiKey 请求头中包含 API 密钥。HTTP 请求头名称不区分大小写；请使用此处给出的拼写，并保持密钥值完全不变。
Content-Type 请求头：
提示： 可以使用 API Playground测试密钥，无需编写代码。
请求要求
每次 API 调用都必须满足以下要求： 仅支持 HTTPS。 所有请求都必须使用https://。纯 HTTP 请求会被拒绝。
ApiKey 请求头。 每个请求都必须包含。无需 OAuth、Bearer 令牌，也不支持查询参数身份验证。
Content-Type 请求头。 POST 请求必需。将其设为 application/json，并通过 JSON 请求体传递参数。
HTTP 方法。 不同操作使用 GET 或 POST。API 参考列出了各端点所用的方法。
管理 API 密钥
查找密钥。 当前密钥显示在控制台概览页。新账号包含 100 次免费请求，无需绑定银行卡即可立即使用第一个密钥。 创建或删除密钥。 要生成新密钥或撤销现有密钥，请前往控制台中的 API Keys 页面。 监控用量。 可通过用量统计页面，或以编程方式调用GET /key-usage-info，追踪请求历史和剩余配额。
重要： 删除或替换密钥后，仍使用旧密钥的应用会立即收到 401 Unauthorized 错误。撤销密钥之前，请先更新集成。
安全最佳实践
不要在客户端代码中暴露密钥。 不要从浏览器、移动应用或任何前端环境直接调用 Sorsa API，否则密钥会暴露在浏览器开发者工具、网络日志和源代码中。始终通过自己的后端服务器转发请求。 使用环境变量。 将密钥存储在.env 文件或平台的机密管理服务中，例如 AWS Secrets Manager、Vercel Environment Variables、Railway Variables 等。不要把密钥硬编码在源文件中。
不要将密钥纳入版本控制。 把 .env 添加到 .gitignore。不要将 API 密钥提交至 GitHub、GitLab 或 Bitbucket 的公开或私有仓库。
密钥泄露后立即更换。 如果不慎在代码提交、截图或公开论坛中泄露密钥，请前往 API Keys 页面，删除已泄露密钥并生成新密钥。旧密钥会立即失效。
故障排查
401 UnauthorizedApiKey 请求头缺失、名称拼写错误，或密钥已被删除或本身无效。检查名称确实是 ApiKey，而不是 Api-Key 或 Authorization。
403 Forbidden
密钥有效，但订阅已过期或月度请求配额已耗尽。通过控制台或调用 GET /key-usage-info 检查剩余次数。
429 Too Many Requests
请求速度超过上限（所有套餐均为每秒 20 次）。在调用之间加入短暂退避并重试。详情和重试策略请参阅速率限制。
浏览器中的 CORS 错误
出现 CORS 错误通常意味着你正在通过前端 JavaScript 调用 API。Sorsa API 仅面向服务端使用。请将 API 调用移至后端服务或无服务器函数。