---
title: OAuth 參考
url: https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference
description: 端點、用戶端驗證、請求參數、範圍、權杖回應、撤銷、有效期限、重新導向 URI 規則以及錯誤。
---

<Warning>
  Claude Platform OAuth 是一項 Beta Service：依據您與 Anthropic 之間的協議（例如[商業服務條款](https://www.anthropic.com/legal/commercial-terms)及[特定服務條款](https://www.anthropic.com/legal/service-specific-terms)）所提供的預先發布軟體。端點、參數和行為在 Beta 期間可能會變更。它可能不適合用於正式環境。
</Warning>

此頁面彙整了 [Claude Platform OAuth](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/overview) 的端點、參數、驗證規則和錯誤對應。如需逐步說明，請參閱 [Linked billing](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/organization-billing-connections)。

## 端點

| 端點                          | URL                                                                     |
| --------------------------- | ----------------------------------------------------------------------- |
| 簽發者（Issuer）                 | `https://identity.anthropic.com/users`                                  |
| 探索文件                        | `https://identity.anthropic.com/users/.well-known/openid-configuration` |
| 簽署金鑰（JWKS）                  | 探索文件中的 `jwks_uri`，託管於 `identity.anthropic.com`                          |
| 授權端點（登入與同意頁面）               | `https://auth.claude.com/oauth/authorize`                               |
| 推送授權請求（PAR）端點               | `https://auth.claude.com/v1/oauth/par`                                  |
| 權杖端點                        | `https://auth.claude.com/v1/oauth/token`                                |
| 撤銷端點                        | `https://auth.claude.com/v1/oauth/revoke`                               |
| Claude API（使用者設定檔及向客戶計費的請求） | `https://api.anthropic.com`                                             |

請從探索文件讀取簽署金鑰，而非將其寫死在程式碼中。探索文件並未列出 PAR 端點或撤銷端點，因此請使用此表格中的 URL。

## 探索文件值

| 欄位                                      | 值                                                |
| --------------------------------------- | ------------------------------------------------ |
| `issuer`                                | `https://identity.anthropic.com/users`           |
| `authorization_endpoint`                | `https://auth.claude.com/oauth/authorize`        |
| `token_endpoint`                        | `https://auth.claude.com/v1/oauth/token`         |
| `jwks_uri`                              | `https://identity.anthropic.com/users/jwks.json` |
| `response_types_supported`              | `code`                                           |
| `grant_types_supported`                 | `authorization_code`、`refresh_token`             |
| `code_challenge_methods_supported`      | `S256`                                           |
| `token_endpoint_auth_methods_supported` | `private_key_jwt`                                |
| `id_token_signing_alg_values_supported` | `ES256`                                          |
| `scopes_supported`                      | `openid`、`email`                                 |
| `subject_types_supported`               | `public`、`pairwise`                              |

只有在客戶同時核准 `offline_access` 與 `billing:attribution` 時，`auth.claude.com` 才會為 Linked billing 傳回重新整理權杖：請參閱[計費連線的 OAuth 權杖](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection)。

## 用戶端驗證

`auth.claude.com` 使用 `private_key_jwt` 方法（[RFC 7523](https://www.rfc-editor.org/rfc/rfc7523)）驗證機密用戶端。請在每個傳送至 PAR 端點、權杖端點和撤銷端點的請求中傳送這些參數。切勿在 URL 查詢字串中傳送憑證：`auth.claude.com` 會拒絕它們。

| 參數                      | 值                                                                                                                                        |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id`             | 您的 OAuth 應用程式的用戶端 ID                                                                                                                     |
| `client_assertion_type` | `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`                                                                                 |
| `client_assertion`      | 來自您身分識別提供者的 JWT，包含[用戶端斷言宣告](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#client-assertion-claims)中的宣告 |

### 用戶端斷言宣告

「Client assertion」（用戶端斷言）必須包含以下所有宣告，且其標頭必須包含您 JWKS 中某個金鑰的 `kid`。

| 宣告    | 要求                                                                                                                         |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| `iss` | 您身分識別提供者的簽發者 URL，必須與透過[工作負載身分聯合](https://platform.claude.com/docs/zh-TW/manage-claude/workload-identity-federation)註冊的完全相同 |
| `sub` | 若您有設定主體模式，則為符合您應用程式用戶端驗證設定中主體模式的值                                                                                          |
| `aud` | 恰好一個受眾：即您應用程式用戶端驗證設定中的值。`auth.claude.com` 會拒絕列出多個受眾的斷言。                                                                    |
| `iat` | 您的身分識別提供者簽發 JWT 的時間                                                                                                        |
| `exp` | 到期時間，不得晚於 `iat` 之後 1 小時。請盡可能使用較短的有效期限：任何攔截到斷言的人都可以在其到期前使用它。                                                                |

斷言承載範例：

```json
{
  "iss": "https://idp.example.com",
  "sub": "workload:prod:claude-integration-backend",
  "aud": "YOUR_CONFIGURED_AUDIENCE",
  "iat": 1791230000,
  "exp": 1791230300
}
```

請在您的後端允許的範圍內，將主體模式和宣告條件設定得越窄越好。`auth.claude.com` 會接受來自您身分識別提供者且符合這些條件的任何 JWT，作為您應用程式的驗證。

## 授權請求參數

請將這些參數（`request_uri` 除外）放在推送授權請求的 JSON 主體中。

| 參數                       | Linked billing | 說明                                                                                                                                                                  |
| ------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `response_type`          | 必要             | 值為 `code`                                                                                                                                                           |
| `client_id`              | 必要             | 您的 OAuth 應用程式的用戶端 ID                                                                                                                                                |
| `redirect_uri`           | 必要             | 與已註冊的重新導向 URI 完全相符的 URI，最多 2,048 個字元                                                                                                                                |
| `scope`                  | 必要             | 計費連線為 `billing:attribution` 或 `billing:attribution offline_access`。請參閱[範圍](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#scopes)。 |
| `state`                  | 必要             | 一個隨機、單次使用的值，最多 2,048 個字元，您會在回呼時檢查它                                                                                                                                  |
| `code_challenge`         | 必要             | `BASE64URL(SHA256(code_verifier))`，其中 `code_verifier` 為 43 至 128 個字元                                                                                                |
| `code_challenge_method`  | 必要             | 值為 `S256`                                                                                                                                                           |
| `connection_type`        | 必要             | 值為 `organization_shared`。此值會請求用於計費的組織連線。                                                                                                                            |
| `connection_auth_target` | 必要             | 連線的請求要路由至哪個組織。對於 Linked billing，請傳送 `platform`（OAuth 應用程式的擁有者）。                                                                                                     |
| `user_profile_id`        | 必要             | 您組織中代表該客戶的有效使用者設定檔 ID                                                                                                                                               |
| `request_uri`            | 必要             | PAR 端點傳回的值。請將它連同 `client_id` 傳送至授權端點，不附帶其他參數。                                                                                                                       |

PAR 端點會傳回 HTTP 201，包含 `request_uri` 和 `expires_in`（600 秒）。

## 範圍

| 類別 | 範圍                        | 說明                                                                                                                                                                                                                                   | 連線類型                  | 用戶端類型 |
| -- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- | ----- |
| 一般 | `offline_access`          | 為應用程式提供代表其他所請求範圍的重新整理權杖。在 `organization_shared` 連線上，請僅將它與 `billing:attribution` 一起傳送。                                                                                                                                                | `organization_shared` | 機密    |
| 計費 | `billing:attribution`     | 一種連線，可將客戶指示您發出的 Claude API 請求計費至其 Claude 組織。請單獨傳送此範圍，或與 `offline_access` 一起傳送以同時取得重新整理權杖。請參閱[計費連線的 OAuth 權杖](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection)。 | `organization_shared` | 機密    |
| 計費 | `org:billing_attribution` | 已淘汰：請使用 `billing:attribution`。                                                                                                                                                                                                       | `organization_shared` | 機密    |

## 權杖請求與回應

請以 JSON 主體將權杖請求傳送至 `https://auth.claude.com/v1/oauth/token`。

| 參數                                                     | 值                                                                                                                 |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `grant_type`                                           | `authorization_code`                                                                                              |
| `code`                                                 | 來自回呼的授權碼                                                                                                          |
| `redirect_uri`                                         | 與您在授權請求中傳送的相同 `redirect_uri`                                                                                      |
| `code_verifier`                                        | PKCE 程式碼驗證器                                                                                                       |
| `client_id`、`client_assertion_type`、`client_assertion` | 如[用戶端驗證](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#client-authentication)所述 |

權杖回應包含以下欄位：

| 回應欄位                       | Linked billing                                                                                                                   |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `access_token`             | [連線的存取權杖](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection) |
| `token_type`               | `Bearer`                                                                                                                         |
| `expires_in`               | 最多 `3600`                                                                                                                        |
| `scope`                    | `workspace:inference`                                                                                                            |
| `connection_id`            | 連線 ID，例如 `ocon_EXAMPLE`。請儲存它。                                                                                                    |
| `refresh_token`            | 僅在客戶核准 `offline_access` 時傳回                                                                                                      |
| `refresh_token_expires_in` | 距離 `refresh_token` 到期的秒數。沒有 `refresh_token` 時不存在。                                                                                |

若要重新整理，請傳送設為 `refresh_token` 的 `grant_type`、您的 `refresh_token`，以及[用戶端驗證](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#client-authentication)中的參數。計費連線的重新整理會遵循[計費連線的 OAuth 權杖](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection)中的規則。

## 計費連線的 OAuth 權杖

對於計費連線，權杖端點會傳回該連線的存取權杖。此權杖會在應用程式的 `connection_token_workspace_id` 設定所指定的工作區中，以您應用程式的[營運者服務帳戶](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#terms)身分進行驗證。在 `/v1/messages` 和 `/v1/chat/completions` 上，使用此權杖的請求只會計費至該連線的客戶，不會計費至其他任何對象。當客戶也核准了 `offline_access` 時，權杖端點也會傳回重新整理權杖，而 `refresh_token` 授權會同時更新這兩個權杖。如需設定與逐步說明，請參閱 Linked billing 頁面上的[每個連線的 OAuth token](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection)。

這兩種授權都使用[權杖請求與回應](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#token-request-and-response)中的參數，並搭配[用戶端驗證](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#client-authentication)。重新整理時不得傳送 `scope` 參數。權杖回應包含以下欄位：

| 回應欄位                       | 值                                                       |
| -------------------------- | ------------------------------------------------------- |
| `access_token`             | 連線的存取權杖                                                 |
| `token_type`               | `Bearer`                                                |
| `expires_in`               | 距離存取權杖到期的秒數，最多 `3600`                                   |
| `scope`                    | 一律為 `workspace:inference`                               |
| `connection_id`            | 連線 ID，例如 `ocon_EXAMPLE`。只有 `authorization_code` 授權會傳回它。 |
| `refresh_token`            | 連線的重新整理權杖。僅在客戶核准 `offline_access` 時傳回。                  |
| `refresh_token_expires_in` | 距離 `refresh_token` 到期的秒數                                |

每次重新整理都會傳回新的 `access_token` 和新的 `refresh_token`。您傳送的重新整理權杖會被取代，而先前的存取權杖會在幾分鐘內停止運作。您可以在取代它的那次重新整理之後 30 秒內，再傳送一次已被取代的重新整理權杖，以重複一個您遺失了回應的請求。該第二次請求會傳回另一組新的權杖，並撤銷遺失回應中的那一組：請只使用最新的一組。使用已被取代權杖的第三次請求會收到 `invalid_grant`，在 30 秒之後才送達的第二次請求也是如此。在這 30 秒內，此類請求不會撤銷任何權杖。超過這 30 秒後，它會撤銷該連線的所有權杖並終止連線。[重新整理 token](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection)說明了重新整理的規則和錯誤。

以下每個事件都會撤銷該連線的權杖，包括目前的存取權杖：

* 客戶或您解除連結。
* 客戶針對同一使用者設定檔核准了範圍不同的新授權請求，且您交換了該核准的授權碼。新連線會取代先前的連線。
* 權杖運作所在的工作區遭到封存。

如需了解 Claude API 如何對使用連線存取權杖的請求計費，請參閱[使用連線的存取 token 呼叫 Claude](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token)。

## 撤銷

請以 JSON 或表單編碼的主體，將撤銷請求傳送至 `https://auth.claude.com/v1/oauth/revoke`。此端點遵循 [RFC 7009](https://www.rfc-editor.org/rfc/rfc7009)，並且也接受連線 ID 和使用者設定檔 ID。

請傳送[用戶端驗證](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#client-authentication)中的參數，以及此表格中恰好一個參數。用戶端斷言的 `aud` 是您應用程式用戶端驗證設定中的值，而非撤銷 URL。

| 參數                | 終止的對象                                                                       |
| ----------------- | --------------------------------------------------------------------------- |
| `connection_id`   | 您應用程式的其中一個連線，以 `ocon_` ID 指定                                                |
| `user_profile_id` | 您應用程式在單一使用者設定檔上的所有連線，以 `uprof_` ID 指定                                       |
| `token`           | 對於 Linked billing，請改為傳送 `connection_id` 或 `user_profile_id`：傳送存取權杖不一定會終止連線。 |

`auth.claude.com` 會接受 `token_type_hint`，但會忽略它。

此端點會傳回 HTTP 200，以及該請求所終止之連線的 ID：

```json
{
  "revoked_connection_ids": ["ocon_EXAMPLE"]
}
```

如果權杖或 ID 不明或屬於其他應用程式、連線已經終止，或請求終止了權杖但未終止任何連線，清單會是空的。回應中不會說明是哪一個。

計費連線終止後，Claude API 會以 `user_profile_not_billable` 拒絕向該客戶計費的請求，且該連線的 OAuth 權杖會停止運作。之後請勿依賴以已淘汰的 `org:billing_attribution` 範圍核准之連線的存取權杖：它可能會立即停止運作，也可能持續運作直到到期。

## 有效期限

| 項目                       | 有效期限                       |
| ------------------------ | -------------------------- |
| 來自 PAR 端點的 `request_uri` | 10 分鐘，單次使用                 |
| 授權碼                      | 5 分鐘，單次使用                  |
| `access_token`           | 最多 1 小時                    |
| `refresh_token`          | 自授權碼交換起最多 1 年。重新整理不會延長此期限。 |

這些是目前的值。請從每個回應中讀取 `expires_in` 和 `refresh_token_expires_in`，而非依賴固定值。

## 重新導向 URI 規則

* 每個 `redirect_uri` 都必須與您應用程式上註冊的 URI 完全相符。`auth.claude.com` 不使用萬用字元或前綴比對。
* 每個重新導向 URI 都必須使用 HTTPS，且不得包含片段。位於 `localhost`、`127.0.0.1` 或 `[::1]` 的本機開發 URI 可以使用 HTTP。
* 以星號作為連接埠註冊的本機開發 URI（例如 `http://localhost:*/callback`）可符合任何連接埠。
* 每個應用程式最多可註冊 10 個重新導向 URI。
* 僅當 `redirect_uri` 與已註冊的 URI 相符時，`auth.claude.com` 才會將錯誤傳送至您的重新導向 URI。對於任何其他 `redirect_uri`，`auth.claude.com` 不會重新導向瀏覽器。

## 錯誤

### 重新導向時的錯誤

`auth.claude.com` 會以 `error`、`error_description` 和 `state` 查詢參數的形式，在您的重新導向 URI 上傳回錯誤。它們是標準的 OAuth 2.0 錯誤（[RFC 6749](https://www.rfc-editor.org/rfc/rfc6749)），但 `user_profile_already_linked` 除外，它是 Anthropic 特有的錯誤。

| 錯誤                            | 發生時機                                                                                           | 應向使用者顯示的內容                                                                                                                                                                                                                                        |
| ----------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_denied`               | 該人員拒絕了請求，或無法核准此請求。對於計費連線，該人員必須是 Claude 組織的管理員。                                                 | 說明連線未完成，且請勿假設該人員拒絕了請求。對於計費連線，請依照 Linked billing 指南中的[您的重新導向 URI 收到 `error=access_denied`](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/organization-billing-connections#access-denied)進行，其中列出了各項原因以及應告知該人員的內容。在其他情況下，請該人員與您聯繫。 |
| `server_error`                | `auth.claude.com` 無法處理該請求。                                                                     | 請使用者再試一次。                                                                                                                                                                                                                                         |
| `user_profile_already_linked` | 僅限 Linked billing。客戶的組織已透過其他使用者設定檔連結至您的應用程式。每個客戶組織只能與您的應用程式建立一個連線。`auth.claude.com` 已請管理員與您聯繫。 | 說明其組織已連結至您的應用程式。                                                                                                                                                                                                                                  |

如果 `request_uri` 已過期或您已使用過它，`auth.claude.com` 會顯示錯誤頁面，且不會將瀏覽器重新導向回您的應用程式。請以新的推送授權請求重新開始流程。

### 來自 PAR 和權杖端點的錯誤

這些端點會傳回包含 `error` 和 `error_description` 的 JSON 主體。

| 錯誤                            | 發生時機                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `invalid_request`             | 必要參數遺失或無效，例如缺少 `state` 或 PKCE 挑戰，或 `user_profile_id` 不是您組織中有效使用者設定檔的 ID。                                                                                                                                                                                                                                                                                                                                                       |
| `invalid_client`              | `auth.claude.com` 無法驗證您的應用程式：用戶端 ID 不明，或用戶端斷言驗證失敗。請依照您應用程式的用戶端驗證設定檢查斷言的 `iss`、`sub` 和 `aud`，並確認您的身分識別提供者是以您 JWKS 中的金鑰簽署它。                                                                                                                                                                                                                                                                                                      |
| `invalid_scope`               | 此應用程式或此連線類型不允許所請求的範圍。對於[計費連線的權杖](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection)，這也表示重新整理時傳送了它不接受的 `scope` 參數，或 `billing:attribution` 已不再為您的應用程式註冊。在授權碼交換時，第二種原因會耗用掉該授權碼。                                                                                                                                                                               |
| `invalid_grant`               | 授權碼已過期、您已使用過它，或它與 `redirect_uri` 或 `code_verifier` 不相符。對於重新整理，表示重新整理權杖已過期或不再有效：請依照[重新整理 token](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection)進行。                                                                                                                                                                                                     |
| `unauthorized_client`         | 您的應用程式未設定為可處理此請求。對於 Linked billing，請先檢查應用程式的營運者服務帳戶及其工作區：請參閱[授權碼交換傳回 `unauthorized_client`](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/organization-billing-connections#code-exchange-unauthorized-client)。對於[計費連線的權杖](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection)，`error_description` 會說明原因，例如缺少工作區。此拒絕不會耗用授權碼，也不會撤銷任何重新整理權杖。 |
| `user_profile_already_linked` | 僅限 Linked billing，來自權杖端點。在核准與此請求之間，該使用者設定檔已透過其他客戶組織連結至您的應用程式，或客戶的組織已透過其他使用者設定檔連結。                                                                                                                                                                                                                                                                                                                                              |

如果 `auth.claude.com` 對請求進行速率限制、發生服務中斷，或收到不明的 `grant_type` 或超過長度限制的參數，它會以不同的格式傳回錯誤，該格式可能不是 JSON。僅在 HTTP 429 和 5xx 回應時搭配退避機制重試。請將任何其他狀態視為請求中的錯誤。對於計費連線的重新整理，請依照[重新整理 token](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection)進行，而非使用一般的退避機制。如果回應包含 `retry-after` 標頭，請至少等待該時間。請從您自己的程式碼傳送下一個請求，不要依賴 HTTP 用戶端程式庫的自動重試：它們可能不會針對此類回應執行。[重新整理 token](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection)也說明了何時重試是安全的，因為已使用過的重新整理權杖在您再次傳送時可能會終止連線。

### 來自撤銷端點的錯誤

對於 `auth.claude.com` 拒絕的大多數請求，撤銷端點會傳回 HTTP 400，以及包含 `error` 和 `error_description` 的 JSON 主體。

| 錯誤                    | 發生時機                                                                                                                                                                                                     |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_request`     | 必要參數遺失或無效，例如缺少 `client_id`。請求未傳送 `token`、`connection_id` 和 `user_profile_id` 中的任何一個，或傳送了其中多個。ID 格式錯誤，例如前綴錯誤。憑證或 `token` 位於 URL 查詢字串中。該使用者設定檔的連線過多，無法在單一請求中處理：該請求可能已終止其中部分連線，因此請以 `connection_id` 終止其餘連線。 |
| `invalid_client`      | `auth.claude.com` 無法驗證您的應用程式。如需檢查項目，請參閱[來自 PAR 和權杖端點的錯誤](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#errors-from-the-par-and-token-endpoints)中的 `invalid_client`。    |
| `unauthorized_client` | 您的應用程式未設定為可處理此請求。請聯繫您的 Anthropic 客戶團隊。                                                                                                                                                                   |

下一個表格中的回應使用不同的格式，該格式可能不是 JSON。當主體為 JSON 時，`error` 是物件而非字串。

| 狀態  | 發生時機                       | 應採取的行動                                                                                                                                                 |
| --- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 400 | 某個參數超過其長度限制。               | 修正該請求。請勿重試。                                                                                                                                            |
| 429 | 來自您 IP 位址的失敗請求過多。          | 搭配退避機制重試。                                                                                                                                              |
| 500 | `auth.claude.com` 無法處理該請求。 | 搭配退避機制重試。如果問題持續發生，請聯繫您的 Anthropic 客戶團隊。                                                                                                                |
| 501 | Anthropic 尚未為您的組織啟用此端點。    | 請勿重試。請聯繫您的 Anthropic 客戶團隊。                                                                                                                             |
| 503 | 該請求未完成。它已終止的任何項目會維持終止狀態。   | 搭配退避機制重試，使用相同的參數和新的用戶端斷言。重試會完成其餘部分，且其清單會略過先前請求已終止的連線。如果您傳送的是 `user_profile_id`，請在一天內重試：超過此時間後，重試可能會傳回 200 和空清單，且不會完成任何項目。以各個 `connection_id` 重試則隨時都有效。 |

### 計費錯誤

這些錯誤適用於將 `billing_policy.bill_to` 設為 `"user_profile"`，或以[計費連線的存取權杖](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection)進行驗證的 Claude API 請求。Claude API 不會為被拒絕的請求向任一組織計費。所有 402 和 403 回應都不可重試，但新連線建立後 10 秒內的 `user_profile_not_billable` 拒絕除外。

| 狀態  | 錯誤類型與代碼                                                   | 發生時機                                                                                                                                                                                                                                                                                                                |
| --- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | `invalid_request_error`                                   | 請求傳送了 `billing_policy` 卻未附帶 `user-profiles-billing-2026-10-01` beta 標頭。或者 `billing_policy` 物件有欄位遺失或無效。使用計費連線的存取權杖時，可以省略 `bill_to`。或者請求在允許的組合之外使用程式碼執行。                                                                                                                                                              |
| 400 | `invalid_request_error`、`user_profile_required`           | `bill_to` 為 `"user_profile"`、請求未包含使用者設定檔 ID，且未以計費連線的存取權杖進行驗證。                                                                                                                                                                                                                                                       |
| 400 | `invalid_request_error`，無錯誤代碼                             | 請求以計費連線的存取權杖進行驗證，且將 `bill_to` 設為 `"self"`，或指定了該權杖所限定之使用者設定檔以外的使用者設定檔。這兩種拒絕都會在 `error.message` 中說明問題所在。                                                                                                                                                                                                              |
| 401 | `authentication_error`                                    | 請求所使用的計費連線存取權杖已過期、已被重新整理取代，或其連線已終止。訊息會說明該權杖是已過期還是已被撤銷。請使用目前的存取權杖重新傳送請求，若連線已終止，則請重新連結客戶。連線終止後，每個使用其存取權杖的新請求都可能收到此 401 或 403 `user_profile_not_billable`，順序不固定。                                                                                                                                                       |
| 402 | `billing_error`、`linked_organization_spend_limit_reached` | 客戶組織已達到其為您的 OAuth 應用程式或整個組織所設定的支出限制。當該組織沒有可支付該請求的額度時，也會傳送相同的代碼。回應中不會說明是哪一個。請客戶檢查這兩項限制及其額度餘額。Linked billing 的[預期的錯誤](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/organization-billing-connections#expected-errors)一節說明了各項的設定位置以及需要變更的內容。                                                         |
| 402 | `billing_error`、`linked_organization_billing_unavailable` | 由於客戶組織本身的 Anthropic 帳戶有問題，Anthropic 目前無法向該組織計費。當該組織的額度用盡時，相同的代碼也會終止 Claude 已開始的回覆。請客戶向 Anthropic 確認其計費狀態。                                                                                                                                                                                                           |
| 403 | `permission_error`，無錯誤代碼                                  | Anthropic 並未直接向您的組織計費，因此無法代表您向客戶計費。                                                                                                                                                                                                                                                                                 |
| 403 | `permission_error`、`user_profile_not_billable`            | 該使用者設定檔未連線至任何客戶組織、管理員或您的後端已終止連線、客戶組織並未就其 API 用量直接向 Anthropic 付款（預付額度和發票計費皆算在內），或請求未以您應用程式的服務帳戶身分進行驗證。回應中不會說明是哪一個。連線終止後，連線的存取權杖也可能收到此錯誤。[`user_profile_not_billable` 的原因](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/organization-billing-connections#user-profile-not-billable)說明了各項情況需要檢查的內容。 |
| 503 | `overloaded_error`                                        | Claude API 暫時無法確認是否能向客戶計費。請重試該請求。如果回應包含 `retry-after` 標頭，請等待該時間後再重試。                                                                                                                                                                                                                                                |

在 `/v1/messages` 上，錯誤代碼位於 `error.details.error_code` 中。在 `/v1/chat/completions` 上，`error.type` 一律為 `invalid_request_error`，`error.code` 包含 Anthropic 錯誤類型（例如 `permission_error` 或 `billing_error`），且回應中沒有錯誤代碼，因此請依據 HTTP 狀態和 `error.code` 進行比對。

## 標準

| 標準                                                             | 適用範圍                                                     |
| -------------------------------------------------------------- | -------------------------------------------------------- |
| [OAuth 2.0 (RFC 6749)](https://www.rfc-editor.org/rfc/rfc6749) | 授權碼流程、權杖端點和錯誤回應                                          |
| [PKCE (RFC 7636)](https://www.rfc-editor.org/rfc/rfc7636)      | 每個授權請求皆必須使用 `S256`                                       |
| [推送授權請求（RFC 9126）](https://www.rfc-editor.org/rfc/rfc9126)     | Linked billing 為必要。                                      |
| [權杖撤銷（RFC 7009）](https://www.rfc-editor.org/rfc/rfc7009)       | 撤銷端點，它也接受連線 ID 和使用者設定檔 ID，並傳回其所終止之連線的 ID                 |
| [JWT 用戶端驗證（RFC 7523）](https://www.rfc-editor.org/rfc/rfc7523)  | PAR、權杖和撤銷端點的 `private_key_jwt` 用戶端驗證，以及向客戶計費之請求的服務帳戶權杖交換 |

## 這些頁面中使用的術語

以下定義僅適用於 Claude Platform OAuth。

| 術語           | 意義                                                                                                                                                                                                                                                       |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude 組織    | 在 Anthropic 的組織帳戶。您的公司擁有一個，每個為計費而連結其組織的客戶也各擁有一個。                                                                                                                                                                                                         |
| 管理員          | Claude 組織中具有管理員或帳單角色的成員。                                                                                                                                                                                                                                 |
| OAuth 應用程式   | 您 Claude 組織中的註冊項目，用於向 `auth.claude.com` 識別您的產品。它具有用戶端 ID、名稱、標誌、首頁 URL、重新導向 URI，以及其支援的連線類型。                                                                                                                                                               |
| 連線類型         | 由誰核准連線：代表整個組織的管理員（`organization_shared`，用於 Linked billing）。                                                                                                                                                                                              |
| 身分識別提供者      | 您自有基礎架構中的服務，負責為您的後端簽署短期 JWT，並以 JSON Web Key Set（JWKS）發布其公開金鑰，例如您雲端供應商的工作負載身分識別服務，或您自己符合 OIDC 規範的簽發者。在這些頁面中，「您的身分識別提供者」一律指此服務，而非 Anthropic。                                                                                                               |
| 用戶端斷言        | 由您的身分識別提供者簽署、並由您的後端傳送以驗證您 OAuth 應用程式的短期 JWT。這就是 `private_key_jwt` 用戶端驗證方法（RFC 7523）。                                                                                                                                                                     |
| 推送授權請求（PAR）  | 一種請求，您的後端會將授權參數直接傳送至 `auth.claude.com`，並收到用於瀏覽器重新導向的 `request_uri`（RFC 9126）。                                                                                                                                                                            |
| 工作負載身分聯合     | Claude Console 的功能，您的組織透過它註冊您的身分識別提供者，讓 Anthropic 接受以您 JWKS 中的金鑰簽署的 JWT。                                                                                                                                                                                 |
| 探索文件         | 列出 Anthropic 簽發者、端點和簽署金鑰的 OIDC 文件。                                                                                                                                                                                                                       |
| 使用者設定檔       | 您在自己的 Claude 組織中建立、用以代表您某位客戶的記錄。計費連線會將使用者設定檔連結至該客戶的 Claude 組織。                                                                                                                                                                                           |
| 服務帳戶         | 您 Claude 組織中的非人類帳戶。對於 Linked billing，您的 OAuth 應用程式會連結至一個服務帳戶，即其營運者服務帳戶，且您的後端在傳送向客戶計費的請求時，會以該服務帳戶的身分進行驗證。                                                                                                                                                 |
| 連線的 OAuth 權杖 | `auth.claude.com` 為計費連線傳回的存取權杖，以及當客戶也核准了 `offline_access` 時所傳回的重新整理權杖。此存取權杖會以營運者服務帳戶的身分進行驗證，且只能向該連線的使用者設定檔計費。請參閱[計費連線的 OAuth 權杖](https://platform.claude.com/docs/zh-TW/manage-claude/oauth-apps/oauth-reference#oauth-tokens-for-a-billing-connection)。 |
