From b0bd3bca1e213523d5917fd044328cbd73fca766 Mon Sep 17 00:00:00 2001 From: kojimaru Date: Wed, 22 Apr 2026 09:43:38 +0900 Subject: [PATCH 01/11] Add more patterns of error description and solution for 400 status codes --- .../permissions-and-errors/common-errors.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/content/guides/api-calls/permissions-and-errors/common-errors.md b/content/guides/api-calls/permissions-and-errors/common-errors.md index 6500b1aef..7b0b21429 100644 --- a/content/guides/api-calls/permissions-and-errors/common-errors.md +++ b/content/guides/api-calls/permissions-and-errors/common-errors.md @@ -57,6 +57,54 @@ for solution to common errors encountered when working with the Box APIs. | **Error** | `bad_request`| |**Message** | | | **Solution** | Required parameters supplied in the API request are either missing or invalid. Check the extended error message in the response body for more details. | +| | | +| **Error** | `unauthorized_client` | +| **Message** | This app is not authorized by the enterprise admin. | +| **Solution** | Server authentication applications using JWT or Client Credentials Grant must be authorized by a Box Admin before use. Follow the steps in [Platform App Approval](https://developer.box.com/guides/authorization/platform-app-approval) to complete authorization.| +| | | +| **Error** | `invalid_client` | +| **Message** | The client credentials are invalid. | +| **Solution** | Verify the Client ID and Client Secret in the token request match the Developer Console.| +| | | +| **Error** | `invalid_credentials` | +| **Message** | Invalid refresh token | +| **Solution** | The refresh token may be invalid, revoked, or expired. Correct your application's refresh-token handling and obtain a new token pair through the OAuth 2.0 authorization flow if needed. | +| | | +| **Error** | `invalid_request` | +| **Message** | The grant type is unauthorized for this client_id. | +| **Solution** | You may be requesting a token using standard OAuth 2.0 while the app is configured for Server Authentication (JWT), or the opposite. Use the token request type that matches your app's authentication method. See [The grant type is unauthorized for this client_id](https://support.box.com/hc/en-us/articles/360044193033-API-Authentication-The-grant-type-is-unauthorized-for-this-client-id). | +| | | +| **Error** | `invalid_request` | +| **Message** | Invalid `grant_type` parameter or parameter missing. | +| **Solution** | You may be sending token requests to wrong domains (such as `app.box.com` or `www.box.com`). Send token requests to `https://api.box.com`. Use the `grant_type` and other parameters required for your flow (authorization code, refresh token, JWT assertion, and so on). | +| | | +| **Error** | `invalid_request` | +| **Message** | Cannot obtain user token based on the enterprise configuration for your app. | +| **Solution** | Your app may be missing a scope or configuration needed to request a user token. See [Cannot Obtain Token Based on Enterprise Configuration for Your App](https://support.box.com/hc/en-us/articles/360044192553). | +| | | +| **Error** | `invalid_grant` | +| **Message** | The authorization code has expired. | +| **Solution** | Authorization codes expire shortly after they are issued (on the order of tens of seconds). Exchange the code for tokens immediately after the user is redirected back to your application. | +| | | +| **Error** | `invalid_grant` | +| **Message** | Please check the `sub` claim. | +| **Solution** | For JWT auth, set the `sub` (subject) claim to the correct user ID or enterprise ID depending on `box_sub_type`. See [JWT `invalid_grant`: check the `sub` claim](https://support.box.com/hc/en-us/articles/360043691734). | +| | | +| **Error** | `invalid_grant` | +| **Message** | Please check the `jti` claim. A unique `jti` value is required. | +| **Solution** | Ensure the JWT ID (`jti`) is set to a valid, unique value for each assertion. The same `jti` cannot be reused. | +| | | +| **Error** | `invalid_grant` | +| **Message** | Please check the `iss` claim. | +| **Solution** | The issuer (`iss`) claim must match the OAuth client ID for your application when using JWT authentication. | +| | | +| **Error** | `invalid_grant` | +| **Message** | Signature verification error. The public key identified by `kid` must correspond to the private key used for signing. | +| **Solution** | Use the public/private keypair associated with your app in the Developer Console. If you rotate keys, add the new key, remove the old one, update your configuration file with the new keypair and `kid`, then request a new access token. | +| | | +| **Error** | `invalid_grant` | +| **Message** | `kid` invalid, unable to lookup correct key. | +| **Solution** | The key ID (`kid`) in the JWT header must match a public key registered for the application (for example, the `publicKeyID` in your configuration). Confirm you are using the correct configuration file, or generate a new RSA keypair in the Developer Console and update your app to use it. | | | | | **Error** | `cannot_make_collaborated_subfolder_private` | | **Message** | Cannot move a collaborated subfolder to a private folder unless the new owner is explicitly specified. | From 1fec6fe959c8a45bf1ccc8f8f34a92ce1cc22fd3 Mon Sep 17 00:00:00 2001 From: kojimaru Date: Wed, 22 Apr 2026 10:34:23 +0900 Subject: [PATCH 02/11] Move error message for "exp" claim closer to other "invalid_grant" messages --- .../api-calls/permissions-and-errors/common-errors.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/guides/api-calls/permissions-and-errors/common-errors.md b/content/guides/api-calls/permissions-and-errors/common-errors.md index 7b0b21429..0ac78d1cd 100644 --- a/content/guides/api-calls/permissions-and-errors/common-errors.md +++ b/content/guides/api-calls/permissions-and-errors/common-errors.md @@ -105,6 +105,10 @@ for solution to common errors encountered when working with the Box APIs. | **Error** | `invalid_grant` | | **Message** | `kid` invalid, unable to lookup correct key. | | **Solution** | The key ID (`kid`) in the JWT header must match a public key registered for the application (for example, the `publicKeyID` in your configuration). Confirm you are using the correct configuration file, or generate a new RSA keypair in the Developer Console and update your app to use it. | +| | | +| **Error** | `invalid_grant` | +| **Message** | Current date time must be before the expiration date time listed in the 'exp' claim. | +| **Solution** | This error occurs when the Unix time on your local machine and the Box server are out of sync. To fix this error, update the Unix time on your machine to match a synchronized time server, then try the request again. | | | | | **Error** | `cannot_make_collaborated_subfolder_private` | | **Message** | Cannot move a collaborated subfolder to a private folder unless the new owner is explicitly specified. | @@ -129,10 +133,6 @@ for solution to common errors encountered when working with the Box APIs. | **Error** | `invalid_grant` | | **Message** | Verify the authorization code is set correctly in your request, or your application likely needs to get a new authorization code. | | **Solution** | The authorization code supplied in the API request is missing or no longer valid. Possible solutions are to verify that the access token is added correctly in the request. If correctly set, the access token may have expired. Attempt to refresh the access token or fetch a new one. | -| | | -| **Error** | `invalid_grant` | -| **Message** | Current date time must be before the expiration date time listed in the 'exp' claim. | -| **Solution** | This error occurs when the Unix time on your local machine and the Box server are out of sync. To fix this error, update the Unix time on your machine to match a synchronized time server, then try the request again. | | | | | **Error** | `invalid_limit` | | **Message** | Limit is not a valid number | From 89449928b3ab36e2588438071b1a229b64350561 Mon Sep 17 00:00:00 2001 From: kojimaru Date: Wed, 22 Apr 2026 10:43:23 +0900 Subject: [PATCH 03/11] Remove the unused error message "Verify the authorization code is set correctly in your request, or your application likely needs to get a new authorization code." --- .../guides/api-calls/permissions-and-errors/common-errors.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/content/guides/api-calls/permissions-and-errors/common-errors.md b/content/guides/api-calls/permissions-and-errors/common-errors.md index 0ac78d1cd..7ef6b2dee 100644 --- a/content/guides/api-calls/permissions-and-errors/common-errors.md +++ b/content/guides/api-calls/permissions-and-errors/common-errors.md @@ -129,10 +129,6 @@ for solution to common errors encountered when working with the Box APIs. | **Error** | `invalid_collaboration_item` | | **Message** | Item type must be specified and set to 'folder' | | **Solution** | The `item.type` field of the collaboration item should be set to folder.| -| | | -| **Error** | `invalid_grant` | -| **Message** | Verify the authorization code is set correctly in your request, or your application likely needs to get a new authorization code. | -| **Solution** | The authorization code supplied in the API request is missing or no longer valid. Possible solutions are to verify that the access token is added correctly in the request. If correctly set, the access token may have expired. Attempt to refresh the access token or fetch a new one. | | | | | **Error** | `invalid_limit` | | **Message** | Limit is not a valid number | From 8df2b3db536b4ca296a6017a99c7e402190b665f Mon Sep 17 00:00:00 2001 From: kojimaru Date: Wed, 22 Apr 2026 11:14:49 +0900 Subject: [PATCH 04/11] Add invalid_token error --- .../guides/api-calls/permissions-and-errors/common-errors.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/guides/api-calls/permissions-and-errors/common-errors.md b/content/guides/api-calls/permissions-and-errors/common-errors.md index 7ef6b2dee..5836aac9e 100644 --- a/content/guides/api-calls/permissions-and-errors/common-errors.md +++ b/content/guides/api-calls/permissions-and-errors/common-errors.md @@ -200,6 +200,10 @@ for solution to common errors encountered when working with the Box APIs. | **Error** | `unauthorized` | | **Message** | Unauthorized | | **Solution** | Authorization token is not authorized, check extended error message in body for more details. | +| | | +| **Error** | `invalid_token` | +| **Message** | The access token provided is invalid. | +| **Solution** | The access token may be incorrect, corrupted, or expired—for example, because of a typo, using a token from another environment, or revocation or deletion. Obtain a new access token from the token endpoint. For OAuth 2.0 auth, you can refresh an expired access token; see [Refresh a token](https://developer.box.com/guides/authentication/tokens/refresh). | ### 403 Forbidden From eb3b80dd7291bd06e2bc389c26b755dff57d871d Mon Sep 17 00:00:00 2001 From: kojimaru Date: Wed, 22 Apr 2026 11:15:21 +0900 Subject: [PATCH 05/11] Fix the error code for "Invalid refresh token" --- .../guides/api-calls/permissions-and-errors/common-errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/api-calls/permissions-and-errors/common-errors.md b/content/guides/api-calls/permissions-and-errors/common-errors.md index 5836aac9e..127e56f3d 100644 --- a/content/guides/api-calls/permissions-and-errors/common-errors.md +++ b/content/guides/api-calls/permissions-and-errors/common-errors.md @@ -66,7 +66,7 @@ for solution to common errors encountered when working with the Box APIs. | **Message** | The client credentials are invalid. | | **Solution** | Verify the Client ID and Client Secret in the token request match the Developer Console.| | | | -| **Error** | `invalid_credentials` | +| **Error** | `invalid_grant` | | **Message** | Invalid refresh token | | **Solution** | The refresh token may be invalid, revoked, or expired. Correct your application's refresh-token handling and obtain a new token pair through the OAuth 2.0 authorization flow if needed. | | | | From 1b1b4008ef4da4f164b6b91949139473fa8ea693 Mon Sep 17 00:00:00 2001 From: kojimaru Date: Wed, 22 Apr 2026 11:21:59 +0900 Subject: [PATCH 06/11] Use guide:// links in common-errors for internal guide URLs --- .../guides/api-calls/permissions-and-errors/common-errors.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/guides/api-calls/permissions-and-errors/common-errors.md b/content/guides/api-calls/permissions-and-errors/common-errors.md index 127e56f3d..d0b08921a 100644 --- a/content/guides/api-calls/permissions-and-errors/common-errors.md +++ b/content/guides/api-calls/permissions-and-errors/common-errors.md @@ -60,7 +60,7 @@ for solution to common errors encountered when working with the Box APIs. | | | | **Error** | `unauthorized_client` | | **Message** | This app is not authorized by the enterprise admin. | -| **Solution** | Server authentication applications using JWT or Client Credentials Grant must be authorized by a Box Admin before use. Follow the steps in [Platform App Approval](https://developer.box.com/guides/authorization/platform-app-approval) to complete authorization.| +| **Solution** | Server authentication applications using JWT or Client Credentials Grant must be authorized by a Box Admin before use. Follow the steps in [Platform App Approval](guide://authorization/platform-app-approval) to complete authorization. | | | | | **Error** | `invalid_client` | | **Message** | The client credentials are invalid. | @@ -203,7 +203,7 @@ for solution to common errors encountered when working with the Box APIs. | | | | **Error** | `invalid_token` | | **Message** | The access token provided is invalid. | -| **Solution** | The access token may be incorrect, corrupted, or expired—for example, because of a typo, using a token from another environment, or revocation or deletion. Obtain a new access token from the token endpoint. For OAuth 2.0 auth, you can refresh an expired access token; see [Refresh a token](https://developer.box.com/guides/authentication/tokens/refresh). | +| **Solution** | The access token may be incorrect, corrupted, or expired—for example, because of a typo, using a token from another environment, or revocation or deletion. Obtain a new access token from the token endpoint. For OAuth 2.0 auth, you can refresh an expired access token; see [Refresh a token](guide://authentication/tokens/refresh). | ### 403 Forbidden From f49ee0b5d7d9b98ef470d0b3a1e8f86f5fb9e589 Mon Sep 17 00:00:00 2001 From: kojimaru14 <30362404+kojimaru14@users.noreply.github.com> Date: Thu, 23 Apr 2026 04:13:02 +0900 Subject: [PATCH 07/11] Update content/guides/api-calls/permissions-and-errors/common-errors.md Co-authored-by: Ian Freeman --- .../guides/api-calls/permissions-and-errors/common-errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/api-calls/permissions-and-errors/common-errors.md b/content/guides/api-calls/permissions-and-errors/common-errors.md index d0b08921a..ebc4e7571 100644 --- a/content/guides/api-calls/permissions-and-errors/common-errors.md +++ b/content/guides/api-calls/permissions-and-errors/common-errors.md @@ -64,7 +64,7 @@ for solution to common errors encountered when working with the Box APIs. | | | | **Error** | `invalid_client` | | **Message** | The client credentials are invalid. | -| **Solution** | Verify the Client ID and Client Secret in the token request match the Developer Console.| +| **Solution** | Verify the Client ID and Client Secret in the token request match the values in the Developer Console.| | | | | **Error** | `invalid_grant` | | **Message** | Invalid refresh token | From 30c9f3832aee2063c9c7d93a66d6851318dd74d3 Mon Sep 17 00:00:00 2001 From: kojimaru14 <30362404+kojimaru14@users.noreply.github.com> Date: Thu, 23 Apr 2026 04:13:16 +0900 Subject: [PATCH 08/11] Update content/guides/api-calls/permissions-and-errors/common-errors.md Co-authored-by: Ian Freeman --- .../guides/api-calls/permissions-and-errors/common-errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/api-calls/permissions-and-errors/common-errors.md b/content/guides/api-calls/permissions-and-errors/common-errors.md index ebc4e7571..293fb64d4 100644 --- a/content/guides/api-calls/permissions-and-errors/common-errors.md +++ b/content/guides/api-calls/permissions-and-errors/common-errors.md @@ -72,7 +72,7 @@ for solution to common errors encountered when working with the Box APIs. | | | | **Error** | `invalid_request` | | **Message** | The grant type is unauthorized for this client_id. | -| **Solution** | You may be requesting a token using standard OAuth 2.0 while the app is configured for Server Authentication (JWT), or the opposite. Use the token request type that matches your app's authentication method. See [The grant type is unauthorized for this client_id](https://support.box.com/hc/en-us/articles/360044193033-API-Authentication-The-grant-type-is-unauthorized-for-this-client-id). | +| **Solution** | You may be requesting a token using standard OAuth 2.0 while the app is configured for Server Authentication (JWT), or vice versa. Use the token request type that matches your app's authentication method. See [The grant type is unauthorized for this client_id](https://support.box.com/hc/en-us/articles/360044193033-API-Authentication-The-grant-type-is-unauthorized-for-this-client-id). | | | | | **Error** | `invalid_request` | | **Message** | Invalid `grant_type` parameter or parameter missing. | From a28b70c176515efb093dd548f770f32e8d9fbe78 Mon Sep 17 00:00:00 2001 From: kojimaru14 <30362404+kojimaru14@users.noreply.github.com> Date: Thu, 23 Apr 2026 04:13:24 +0900 Subject: [PATCH 09/11] Update content/guides/api-calls/permissions-and-errors/common-errors.md Co-authored-by: Ian Freeman --- .../guides/api-calls/permissions-and-errors/common-errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/api-calls/permissions-and-errors/common-errors.md b/content/guides/api-calls/permissions-and-errors/common-errors.md index 293fb64d4..f8f11aad5 100644 --- a/content/guides/api-calls/permissions-and-errors/common-errors.md +++ b/content/guides/api-calls/permissions-and-errors/common-errors.md @@ -203,7 +203,7 @@ for solution to common errors encountered when working with the Box APIs. | | | | **Error** | `invalid_token` | | **Message** | The access token provided is invalid. | -| **Solution** | The access token may be incorrect, corrupted, or expired—for example, because of a typo, using a token from another environment, or revocation or deletion. Obtain a new access token from the token endpoint. For OAuth 2.0 auth, you can refresh an expired access token; see [Refresh a token](guide://authentication/tokens/refresh). | +| **Solution** | The access token may be incorrect, corrupted, or expired—for example, because of a typo, using a token from another environment, or revocation or deletion. Obtain a new access token from the token endpoint. For OAuth 2.0 auth, you can refresh an expired access token; see Refresh a token. | ### 403 Forbidden From d630c9e0554d46d0b3a7b36fad4b3201d61f0ad7 Mon Sep 17 00:00:00 2001 From: kojimaru14 <30362404+kojimaru14@users.noreply.github.com> Date: Thu, 23 Apr 2026 04:13:36 +0900 Subject: [PATCH 10/11] Update content/guides/api-calls/permissions-and-errors/common-errors.md Co-authored-by: Ian Freeman --- .../guides/api-calls/permissions-and-errors/common-errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/api-calls/permissions-and-errors/common-errors.md b/content/guides/api-calls/permissions-and-errors/common-errors.md index f8f11aad5..5b8da43ce 100644 --- a/content/guides/api-calls/permissions-and-errors/common-errors.md +++ b/content/guides/api-calls/permissions-and-errors/common-errors.md @@ -60,7 +60,7 @@ for solution to common errors encountered when working with the Box APIs. | | | | **Error** | `unauthorized_client` | | **Message** | This app is not authorized by the enterprise admin. | -| **Solution** | Server authentication applications using JWT or Client Credentials Grant must be authorized by a Box Admin before use. Follow the steps in [Platform App Approval](guide://authorization/platform-app-approval) to complete authorization. | +| **Solution** | Server authentication applications using JWT or Client Credentials Grant must be authorized by a Box Admin before use. Follow the steps in Platform App Approval. | | | | | **Error** | `invalid_client` | | **Message** | The client credentials are invalid. | From c518e8035f4d4e6aa5d29d0a34a0f48b9d63eca9 Mon Sep 17 00:00:00 2001 From: kojimaru Date: Sat, 25 Apr 2026 05:44:15 +0900 Subject: [PATCH 11/11] Add "client_id" to en_US spelling dictionary Hunspell/mdspell does not treat client_id as a normal word, so common-errors.md failed lint:spelling in CI. Bump the dictionary word count to match the new entry. --- content/dictionaries/en_US.dic | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/dictionaries/en_US.dic b/content/dictionaries/en_US.dic index ae7bdffbc..fc93c1f89 100644 --- a/content/dictionaries/en_US.dic +++ b/content/dictionaries/en_US.dic @@ -1,4 +1,4 @@ -49270 +49271 0/nm 0th/pt 1/n1 @@ -16759,6 +16759,7 @@ cliche/MDS click/BZGMDRS clicker/M client/MS +client_id clientele/MS cliff/MS cliffhanger/SM