---
title: API 基礎
description: BillionSend API 的基礎網址、API 金鑰權限、錯誤清單、頻率限制、冪等性金鑰與分頁。
seo:
  title: API 驗證與錯誤
ai:
  exclude: true
---

[API 參考](/docs/zh-hant/api-reference)中的各端點頁面，是由 API 的路由定義自動產生的。[OpenAPI 3.1 規格](/docs/api.openapi.json)與它是同一個來源，只是整合成一個 JSON 檔案。

此 API 與 Resend API 相容：路徑、請求格式與錯誤格式都相同。你可以用 BillionSend 的 [SDK](/docs/zh-hant/sdks) 呼叫，也可以直接透過 HTTP 呼叫。

## 基礎網址

`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-hant/inboxes)**。限制在某個網域的金鑰，只能在該網域內運作：只能從它寄信、只能讀取它的信件，在 `/domains` 下只看得到、也只能更動它，凡是屬於整個團隊的項目（Webhook、抑制清單、範本、聯絡人屬性、`/usage`、`/deliverability`、驗證、`POST /domains`），都會回應 `403 restricted_api_key`；請見 [API 金鑰](/docs/zh-hant/api-keys)。你用 API 建立的金鑰，權限永遠不會比建立它的金鑰更大。

一個團隊最多可以有 25 把啟用中的金鑰。哪些操作需要由擁有者或管理員建立的金鑰，請見[團隊角色](/docs/zh-hant/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-hant/billing)。 |
| `403 sending_paused` | 因為你的退信率或投訴率過高，寄送已暫停。 |
| `404 not_found` | 端點或你要求的項目不存在。 |
| `409 invalid_idempotent_request` | 冪等性金鑰搭配了不同的內容使用。 |
| `415` | 內文不是 `application/json`。 |
| `422 validation_error` | 請求無效。訊息會說明原因。 |
| `422 all_recipients_suppressed` | 所有收件者都已被抑制或退訂。請見[抑制清單](/docs/zh-hant/concepts/suppressions)。 |
| `429 rate_limit_exceeded` | 請求過多。 |
| `429 daily_quota_exceeded` / `monthly_quota_exceeded` | 你方案的寄送額度已用完。請見[方案與限制](/docs/zh-hant/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-hant/receiving)、[收件匣](/docs/zh-hant/inboxes)與 [Agent 安全](/docs/zh-hant/agent-safety)各有自己的錯誤，由那些頁面列出。

## 頻率限制

每把 API 金鑰每分鐘最多 600 個請求，一個團隊的所有金鑰合計 3,000 個。超過限制時，你會收到 `429 rate_limit_exceeded` 與 `retry-after` 標頭。同一個 IP 位址每分鐘超過 20 次驗證失敗，也會以同樣的方式被拒絕。

## 冪等性

`POST /emails` 與 `POST /emails/batch` 接受長度 1 到 256 個字元的 `Idempotency-Key` 標頭。收件匣的回覆、轉寄與草稿寄送，以及收到信件的回覆與轉寄也一樣。用相同的金鑰與相同的內容重試，你會得到原本的回應，而不會多寄一封 Email。相同的金鑰搭配不同的內容，會回應 `409`。

## 分頁

清單端點接受 `limit`（1 到 100，預設 20）與游標 `after`、`before`，兩者都是上一頁中的項目 id。回應中有 `has_more`。清單一律由新到舊排序：

- `after` 帶入某一頁的最後一個 id，回傳更舊的項目。
- `before` 帶入第一個 id，回傳更新的項目。

要取得最新的內容，請把你儲存的最新 id 當作 `before` 傳入。

少數清單使用其他排序，各自的參考頁面會註明：收件匣對話串（最近有活動的在前）、對話串中的 Email（最舊的在前），以及訂閱主題與標籤（最舊的在前，一次全部回傳）。游標沒有對應到任何項目時，會回應 `422 validation_error`（在 `/inboxes` 下則是 `404`）。

## 值得留意的規則

- **附件**只接受內嵌的 base64 `content`。遠端的 `path` URL 會回應 `422`。每封 Email 的附件合計最多 10 MiB，整封 Email 必須小於 40 MB。程式與指令碼（`.exe`、`.js`、`.bat` 等，包含 ZIP 內的檔案）一律會被拒絕。新團隊上，有些風險較高的類型，例如壓縮檔、網頁，以及啟用巨集的 Office 檔案，會被接受，但要先等待審查才會寄出。
- **聯絡人**屬於團隊。沒有 audience 這種東西：audience 端點是[分群](/docs/zh-hant/concepts/segments)的別名。
- **退訂**屬於寄件網域。請見[退訂](/docs/zh-hant/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-hant/concepts/analytics)）。
- **批次聯絡人**：`POST /contacts/batch` 一次建立、`POST /contacts/batch/remove` 一次刪除最多 1,000 位聯絡人。在聯絡人清單加上 `include=properties,topics`，會一併帶入每位聯絡人的屬性與訂閱主題。
- **批次抑制**每個請求最多處理 1,000 個位址。
- **額外的狀態**：群發可以是 `canceled`。
- **收信與收件匣**目前是測試版，支援長輪詢與新信件的即時事件串流。請見[收信](/docs/zh-hant/receiving)與[收件匣](/docs/zh-hant/inboxes)。
- **不支援的**設定會以 `422` 拒絕，而不是被悄悄忽略。

## 簽署下載連結

收到的信件帶有原始郵件與附件的下載連結。它們是不需要 API 金鑰的一般 `GET` URL，有效期限一小時，過期後會回應 `403`。請再向 API 要一個新連結。請見[收信](/docs/zh-hant/receiving)。
