docs: Add troubleshooting guide for HTTP 412 errors in API token documentation#21948
Open
docs: Add troubleshooting guide for HTTP 412 errors in API token documentation#21948
Conversation
Explain that HTTP 412 in Netdata Cloud indicates missing authorization bearer token, not generic precondition failure. Provide step-by-step guide for users to generate API tokens and include them in request headers.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
1 issue found across 1 file
Confidence score: 4/5
- This PR looks safe to merge with low risk, since the only reported issue is a documentation inconsistency rather than a functional code defect.
- In
docs/netdata-cloud/authentication-and-authorization/api-tokens.md, the 412 troubleshooting bullet conflicts with earlier guidance by mixing missing-token behavior with invalid/revoked or insufficient-scope token cases, which could mislead users during debugging. - Given the moderate severity (4/10) and high confidence (9/10), the impact is mainly user-facing clarity in docs, not runtime stability or security behavior changes.
- Pay close attention to
docs/netdata-cloud/authentication-and-authorization/api-tokens.md- align the 412 explanation so token-missing and token-validity/scope scenarios are clearly separated.
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/netdata-cloud/authentication-and-authorization/api-tokens.md">
<violation number="1" location="docs/netdata-cloud/authentication-and-authorization/api-tokens.md:110">
P2: This bullet contradicts the earlier explanation that HTTP 412 specifically means the Authorization token is missing. Listing invalid/revoked or insufficient-scope tokens here makes the troubleshooting guidance internally inconsistent.</violation>
</file>
Architecture diagram
sequenceDiagram
participant Client as User / MCP Client
participant API as Netdata Cloud API
participant Auth as Auth Middleware
participant Settings as User Settings (UI)
Note over Client, Settings: Token Generation (Prerequisite)
Client->>Settings: Navigate to API Tokens
Settings->>Settings: NEW: Generate Token with Scopes
Settings-->>Client: Bearer <token>
Note over Client, Auth: Runtime Request Flow
Client->>API: API Request (e.g., GET /api/v2/nodes)
alt Missing or Malformed "Authorization" Header
API->>Auth: Check for Bearer Token
Auth-->>API: Missing/Invalid
API-->>Client: NEW (Clarified): HTTP 412 Precondition Failed
else Header Exists
API->>Auth: Validate Bearer <token>
Auth->>Auth: Verify Token & Scopes (e.g., scope:all)
alt Valid Token & Authorized Scope
Auth-->>API: Success
API-->>Client: HTTP 200 OK + JSON Response
else Invalid Token or Insufficient Scopes
Auth-->>API: Failed Validation
API-->>Client: NEW (Clarified): HTTP 412 Precondition Failed
end
end
Note right of API: Netdata Cloud uses 412 specifically for<br/>Auth failures instead of generic 401/403.
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
| **Common causes:** | ||
|
|
||
| - Missing `Authorization` header entirely | ||
| - Using an invalid or revoked token |
Contributor
There was a problem hiding this comment.
P2: This bullet contradicts the earlier explanation that HTTP 412 specifically means the Authorization token is missing. Listing invalid/revoked or insufficient-scope tokens here makes the troubleshooting guidance internally inconsistent.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/netdata-cloud/authentication-and-authorization/api-tokens.md, line 110:
<comment>This bullet contradicts the earlier explanation that HTTP 412 specifically means the Authorization token is missing. Listing invalid/revoked or insufficient-scope tokens here makes the troubleshooting guidance internally inconsistent.</comment>
<file context>
@@ -81,3 +81,32 @@ curl -H 'Accept: application/json' -H "Authorization: Bearer <token>" https://ap
+**Common causes:**
+
+- Missing `Authorization` header entirely
+- Using an invalid or revoked token
+- Incorrect header format (missing "Bearer " prefix)
+- Token with insufficient scope for the requested endpoint
</file context>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a troubleshooting section to the Netdata Cloud API token documentation to help users diagnose HTTP 412 responses when calling Cloud API endpoints.
Changes:
- Reformats the “Available Scopes” table for API tokens.
- Adds a “Troubleshooting HTTP 412 Errors” section with guidance on adding
Authorization: Bearer ...headers and generating tokens.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+87
to
+90
| If you receive an HTTP 412 (Precondition Failed) error when accessing Netdata Cloud API endpoints, this indicates that you are trying to access an authenticated endpoint without providing a valid Bearer token in the `Authorization` header. | ||
|
|
||
| In the context of Netdata Cloud, HTTP 412 specifically means that the API request is missing the required authorization token, rather than indicating a generic HTTP precondition failure. | ||
|
|
Comment on lines
+93
to
+97
| 1. **Generate an API token** from your Netdata Cloud settings: | ||
| - Click your profile picture in the bottom-left corner | ||
| - Select "User Settings" | ||
| - Navigate to the API Tokens section | ||
| - Create a new token with appropriate scopes for your use case |
| 2. **Include the token in your request headers**: | ||
|
|
||
| ```console | ||
| curl -H 'Accept: application/json' -H "Authorization: Bearer <your-token-here>" https://app.netdata.cloud/api/v2/nodes |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds a troubleshooting section to the API tokens documentation to help users understand and resolve HTTP 412 errors when accessing Netdata Cloud API endpoints.
Changes
docs/netdata-cloud/authentication-and-authorization/api-tokens.mdMotivation
Users encountering HTTP 412 errors need clear guidance specific to Netdata Cloud, as this status code has a specific meaning in our context (missing authorization token) rather than the generic HTTP precondition failure interpretation.
Testing
Summary by cubic
Adds a troubleshooting guide for HTTP 412 errors to the API token docs, clarifying that in Netdata Cloud this usually means a missing or invalid Authorization Bearer token. Includes steps to generate a token, a correct header example, and common causes to quickly fix failing requests.
Written for commit b245e02. Summary will update on new commits.