---
title: API 基础
description: BillionSend API 的基础 URL、API 密钥权限、错误列表、速率限制、幂等键和分页说明。
seo:
  title: API 认证与错误码
ai:
  exclude: true
---

[API 参考](/docs/zh-hans/api-reference) 中的接口页面由 API 的路由定义生成。[OpenAPI 3.1 规范](/docs/api.openapi.json) 与之同源，只是合成一个 JSON 文件。

BillionSend API 兼容 Resend API：路径、请求结构和错误格式都相同。可以从 BillionSend 的 [SDK](/docs/zh-hans/sdks) 调用，也可以直接发 HTTP 请求。

## 基础 URL

`https://api.billionsend.com`

## 认证

每个请求都要带上控制台 **API 密钥** 页面中的一个 API 密钥：

```
Authorization: Bearer bs_...
```

缺少密钥或密钥格式错误时返回 `401 missing_api_key`，密钥不正确时返回 `401 invalid_api_key`。

密钥有权限级别：

- **完全访问** 可以使用所有接口。
- **仅发送** 只能发送。`/emails` 之外的所有接口都返回 `403 restricted_api_key`，`GET /emails`、`GET /emails/{id}`、`GET /emails/metrics`、`DELETE /emails/{id}` 和所有 `/emails/receiving` 接口也一样，因为它们会返回已存储的内容。

密钥还可以限定在 **某一个域名** 或 **某一个 [收件箱](/docs/zh-hans/inboxes)**。限定在某个域名的密钥只在该域名内工作：只能从它发送，只能读取它的邮件，在 `/domains` 下只能看到并修改它，对属于整个团队的所有内容（Webhook、抑制列表、模板、联系人属性、`/usage`、`/deliverability`、验证、`POST /domains`）都返回 `403 restricted_api_key`，参见 [API 密钥](/docs/zh-hans/api-keys)。你用 API 创建的密钥，权限永远不会比创建它的密钥更宽。

一个团队可以有 25 个有效密钥。哪些操作需要由所有者或管理员创建的密钥，列在 [团队角色](/docs/zh-hans/team-roles) 中。

## 错误

每个错误都是这种结构：

```json
{ "statusCode": 422, "name": "validation_error", "message": "..." }
```

| 状态码与名称 | 含义 |
| --- | --- |
| `400 invalid_parameter` | 请求体不是有效的 JSON。 |
| `401 missing_api_key` / `invalid_api_key` | 没有密钥，或密钥不正确。 |
| `403 restricted_api_key` | 密钥的权限或范围不允许这样做。 |
| `403 forbidden` | 你的角色或密钥不允许这个操作。 |
| `403 plan_limit_reached` | 达到了套餐的某项上限。参见 [套餐与限额](/docs/zh-hans/billing)。 |
| `403 sending_paused` | 因退信率或投诉率过高，发送已暂停。 |
| `404 not_found` | 接口或你请求的对象不存在。 |
| `409 invalid_idempotent_request` | 该幂等键曾用于不同的载荷。 |
| `415` | 请求体不是 `application/json`。 |
| `422 validation_error` | 请求无效。message 中会说明原因。 |
| `422 all_recipients_suppressed` | 所有收件人都被抑制或已退订。参见 [抑制列表](/docs/zh-hans/concepts/suppressions)。 |
| `429 rate_limit_exceeded` | 请求过多。 |
| `429 daily_quota_exceeded` / `monthly_quota_exceeded` | 套餐的发送额度已用完。参见 [套餐与限额](/docs/zh-hans/billing)。 |
| `503 service_unavailable` | 统计存储没有响应。发送不受影响。 |

每个 `429` 都带有 `retry-after` 头，值是需要等待的秒数。

每个响应（无论是否出错）都带有 `x-request-id` 头，即该请求的 id，它与控制台 **日志** 页面上该请求的 id 相同。向我们询问某个请求时，请附上它。

如果收件人的域名永远收不到邮件，例如 `x@example.com`、`x@foo.test` 或 `x@gmail.con`，会被拒绝并返回 `422 validation_error`。在这样的地址上新建联系人也一样。要在不给任何人发邮件的情况下测试，请发送到 `success@simulator.amazonses.com`。

[收信](/docs/zh-hans/receiving)、[收件箱](/docs/zh-hans/inboxes) 和 [Agent 安全](/docs/zh-hans/agent-safety) 各自有额外的错误，在这些页面中列出。

## 速率限制

每个 API 密钥每分钟最多可发出 600 个请求，一个团队的所有密钥合计 3,000 个。超出限制时，你会收到 `429 rate_limit_exceeded` 和 `retry-after` 头。同一个 IP 地址每分钟超过 20 次认证失败，也会以同样方式被拒绝。

## 幂等性

`POST /emails` 和 `POST /emails/batch` 接受长度为 1 到 256 个字符的 `Idempotency-Key` 头。收件箱的回复、转发和草稿发送，以及对收到邮件的回复和转发，也一样。用相同的键和相同的载荷重试，会得到原来的响应，而不是第二封邮件。相同的键搭配不同的载荷会返回 `409`。

## 分页

列表接口接受 `limit`（1 到 100，默认 20）以及游标 `after` 和 `before`，两者都是上一页中的某个条目 id。响应中有 `has_more`。列表默认最新的在前：

- `after` 取一页的最后一个 id，返回更早的条目。
- `before` 取第一个 id，返回更新的条目。

要追上新增的内容，把你保存的最新 id 作为 `before` 传入。

少数列表采用其他顺序，它们的参考页面中会说明：收件箱会话（最近活动的在前）、会话中的邮件（最早的在前），以及订阅主题和标签（最早的在前，一次返回全部）。不匹配任何条目的游标会返回 `422 validation_error`（在 `/inboxes` 下为 `404`）。

## 值得了解的规则

- **附件** 只接受内联 base64 的 `content`。远程 `path` URL 会返回 `422`。每封邮件的附件合计最多 10 MiB，整封邮件必须小于 40 MB。程序和脚本（`.exe`、`.js`、`.bat` 等，包括 ZIP 内的）一律被拒绝。对新团队，一些有风险的类型（例如压缩包、网页和启用宏的 Office 文件）会被接受，但在发送前要等待审核。
- **联系人** 属于团队。没有受众的概念：受众相关接口是 [分群](/docs/zh-hans/concepts/segments) 的别名。
- **退订** 属于发信域名。参见 [退订](/docs/zh-hans/concepts/unsubscribes)。
- **收件人**：`to`、`cc` 和 `bcc` 合计最多 50 个地址，每个都必须是单个邮箱。如果 `to` 中的所有地址都被抑制，发送会返回 `422 all_recipients_suppressed`。
- **邮件头** 采用白名单：任何 `X-*` 名称（`X-SES-*` 和 `X-BillionSend-*` 除外）、会话串联与优先级头，以及 `List-Unsubscribe` 这一对。其他任何邮件头都返回 `422`。
- **主题行** 最长 998 个字符。
- **额外接口**：`GET /usage`（套餐、限额与用量）、`DELETE /emails/{id}`，以及 `GET /emails/metrics`（[数据分析](/docs/zh-hans/concepts/analytics)）。
- **批量联系人**：`POST /contacts/batch` 一次请求最多创建 1,000 位联系人，`POST /contacts/batch/remove` 一次请求最多删除 1,000 位联系人。在联系人列表上加 `include=properties,topics` 会附上每位联系人的属性和订阅主题。
- **批量抑制** 每次请求最多接受 1,000 个地址。
- **额外的状态**：群发可以是 `canceled`。
- **收信和收件箱** 处于 Beta 阶段，对新邮件提供长轮询和实时事件流。参见 [收信](/docs/zh-hans/receiving) 和 [收件箱](/docs/zh-hans/inboxes)。
- **不支持的** 设置会以 `422` 拒绝，而不是被悄悄忽略。

## 带签名的下载链接

收到的邮件带有原始邮件及其附件的下载链接。它们是普通的 `GET` URL，不需要 API 密钥，有效期一小时，过期后返回 `403`。需要时再向 API 请求一个新链接。参见 [收信](/docs/zh-hans/receiving)。
