查询账户余额 - YCloud Docs

概述

Balance API 返回已认证 YCloud 账户的可用余额。可用于运维监控、账单告警以及身份验证检查。

准备工作

安全存储您的 YCloud API 密钥。
确定您的应用程序需要获取余额信息的频率。
根据预期的发送量定义告警阈值。

运作方式

该端点为只读接口，且始终作用于 API 密钥所标识的账户。它不支持在路径或请求体中传入账户 ID。请在监控任务中使用它，而不是在每次发送消息前调用。频繁在单条消息发送前检查余额会增加延迟，且不会预留资金。

请求

GET /balance

curl https://api.ycloud.com/v2/balance \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Accept: application/json"

响应

{
  "amount": 190.0765,
  "currency": "USD"
}

字段	说明
`amount`	可用账户余额。
`currency`	账户所使用的币种。

监控建议

在余额达到可能中断生产流量的水平之前发出告警。
在仪表板和告警中包含币种信息。
为 API 故障设置单独的告警，避免将检查失败误判为余额为零。
严格限制对余额数据的访问权限，将其视为财务信息。

限制与排错

成功的余额响应可验证 API 密钥和 Base URL 的有效性。
即使 API 身份验证成功，余额不足也会影响计费消息产品的发送。
请勿假定金额单位为美元（USD）；请读取 currency。
避免在监控日志输出中记录 API 密钥。

Balance API 参考

查看完整的响应结构并测试只读请求。