HYPERFLEET-378: Add error model and codes standard #56
Conversation
WalkthroughAdds a new HyperFleet Error Model and Codes Standard (hyperfleet/docs/error-model.md) defining RFC 9457 Problem Details usage, HyperFleet extension fields (code, timestamp, trace_id, errors), a machine-readable error code format (HYPERFLEET-{CATEGORY}-{NUMBER}), a taxonomy of problem type URIs with HTTP status mappings, validation error schemas, error propagation/logging guidance, security considerations, and component-specific guidance. Updates API Service API versioning to return Problem Details ( Sequence Diagram(s)sequenceDiagram
autonumber
participant Client as Client
participant API as API Service\n(Problem Details)
participant Internal as Internal Service\n(Business Logic)
participant Log as Logging/Tracing\n(collector)
Client->>API: HTTP request
API->>Internal: Invoke operation / validate
Internal-->>API: Error (validation/auth/conflict/internal)
rect rgba(100,149,237,0.08)
Note right of API: Map internal error -> RFC 9457 Problem Details\n(fields: type, title, status, detail, instance, code, timestamp, trace_id, errors)
end
API->>Log: Emit structured log (trace_id, code, context)
API-->>Client: HTTP 4xx/5xx + application/problem+json (Problem Details)
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Pre-merge checks✅ Passed checks (3 passed)
📜 Recent review detailsConfiguration used: Organization UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🔇 Additional comments (3)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
hyperfleet/docs/error-model.md (1)
145-145: Document the intent of HYPERFLEET-VAL-000 as the multi-error catch-all.Line 145 uses
HYPERFLEET-VAL-000for multiple validation errors, while the standard codes table (line 197) lists VAL-000 as "Request validation failed." The use of000(vs. sequential numbering) as a catch-all is sensible but could be more explicitly documented. Consider adding a note that VAL-000 is reserved for scenarios where multiple distinct fields fail validation (line 140), while specific VAL codes (VAL-001, VAL-002, etc.) are used for single-field errors.Also applies to: 197-197
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
hyperfleet/docs/error-model.md
🧰 Additional context used
🪛 Gitleaks (8.30.0)
hyperfleet/docs/error-model.md
[high] 392-392: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🔇 Additional comments (7)
hyperfleet/docs/error-model.md (7)
23-58: Well-structured error response design.The response structure balances required fields (code, message) with optional metadata (request_id, timestamp, documentation_url). Including
request_idfor tracing and structureddetailsfor validation errors follows REST API best practices.
118-188: Comprehensive validation error structure with clear constraint types.The validation error section provides both single-field (lines 122–136) and multi-field error examples (lines 138–173) with a well-defined taxonomy of constraint types (required, min, max, pattern, enum, format, unique). This enables clients to handle and display validation feedback programmatically.
191-261: Thorough standard error code catalog across all categories.The error code tables span all eight categories (VAL, AUT, AUZ, NTF, CNF, LMT, INT, SVC) with clear, actionable descriptions and example scenarios. The granularity (e.g., NTF-002 "Cluster not found" vs. NTF-003 "NodePool not found") provides specificity for component-specific error handling.
264-318: Strong error wrapping and mapping patterns with security safeguards.The Go code examples (lines 270–318) demonstrate error wrapping best practices using
fmt.Errorfwith%wfor context preservation, and the error response mapping (lines 287–309) shows proper abstraction: internal errors are logged fully, but generic messages are returned to clients. The security considerations (lines 320–325) explicitly warn against exposing stack traces or internal details.
329-349: Clear component-specific guidance and structured logging integration.Component guidelines differentiate appropriately: API service includes request IDs and HTTP status codes, Sentinel logs with resource context, and Adapters report status health vs. business logic failures. The logging example (lines 357–371) aligns with structured logging standards and includes error code, request ID, and context fields.
Also applies to: 353-371
376-410: Client error handling patterns with practical category-based retry logic.The client example (lines 380–410) shows idiomatic Go error type assertion and category-based pattern matching. Each case demonstrates appropriate handling: validation errors shown to users, auth errors trigger re-authentication, version conflicts trigger retry, rate limits respect backoff, and service errors use exponential backoff. This guidance helps SDK consumers implement resilient clients.
414-511: Excellent real-world error response examples.The five example error responses (validation, not found, version conflict, rate limit, internal) provide clear, copy-paste-ready templates. Each includes appropriate HTTP status, headers (e.g., Retry-After on 429), and structured details. These examples serve as a reference for implementation and make the standard tangible.
rafabene
force-pushed
the
HYPERFLEET-378-error-model-standard
branch
from
93e4976 to
7c76541
Compare
rafabene
force-pushed
the
HYPERFLEET-378-error-model-standard
branch
from
7c76541 to
c58c2dd
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
hyperfleet/docs/error-model.md (1)
98-99: Add language specifiers to fenced code blocks.RFC 9457 uses JSON format and
application/problem+jsonmedia type for serialization. Lines 98 and 127 have code blocks that should be explicitly tagged astextor the appropriate language.🔎 Proposed fixes
Line 98 (Type URI Format block):
-\`\`\` +\`\`\`text https://api.hyperfleet.io/errors/{problem-type} -\`\`\` +\`\`\`Line 127 (Error Code Format block):
-\`\`\` +\`\`\`text HYPERFLEET-{CATEGORY}-{NUMBER} -\`\`\` +\`\`\`Also applies to: 127-128
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
hyperfleet/components/api-service/api-versioning.mdhyperfleet/docs/error-model.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
hyperfleet/docs/error-model.md
98-98: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
127-127: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (10)
hyperfleet/components/api-service/api-versioning.md (2)
85-102: Excellent RFC 9457 compliance in error response example.The updated error response properly uses Problem Details with correct Content-Type (
application/problem+json) and includes both standard RFC 9457 fields and appropriate HyperFleet extensions (code, supported_versions). The example clearly demonstrates the standard for API consumers.
184-184: Verify relative path to error-model.md reference.The reference link
../../docs/error-model.mdshould work from the api-versioning.md location, but confirm this path matches your actual file structure and that documentation linking is consistently applied across related files.hyperfleet/docs/error-model.md (8)
175-178: Excellent clarification of HTTP status mapping policy.The mapping policy section (lines 175–178) directly addresses the previous review concern by explicitly stating when to use 400 vs 422 (syntactic vs semantic validation), and clarifying that 502/503/504 all map to the same
SVCcategory with status-specific semantics. This provides the clarity needed for consistent implementation across components.
35-88: RFC 9457 Problem Details implementation is well-structured.The basic structure, standard fields, and HyperFleet extension fields (code, timestamp, trace_id, errors) are clearly defined with a complete example. The section properly aligns with RFC 9457 standards and provides clear guidance for API implementers.
92-117: Problem Types section provides clear URI-to-category mapping.The registered problem types (lines 104–117) establish a comprehensive mapping from RFC 9457 type URIs to HyperFleet error categories and HTTP statuses. This structure enables both human-readable problem types and machine-readable codes, supporting diverse client implementations and debugging workflows.
182-262: Validation error schema is comprehensive and extensible.The validation error details section provides single and multiple error examples with a clear constraint type taxonomy (required, min, max, pattern, enum, format, unique, etc.). The structured error format enables clients to programmatically handle field-level validation failures, improving user experience when building form validators or error recovery logic.
266-336: Error code catalog provides complete reference for all categories.The standard error codes table (lines 270–335) lists specific error codes across all eight categories (VAL, AUT, AUZ, NTF, CNF, LMT, INT, SVC) with clear, actionable titles and descriptions. This comprehensive catalog ensures consistency across HyperFleet components and provides a shared vocabulary for error handling.
339-362: Error wrapping and security guidance is practical and well-reasoned.The section on error wrapping (lines 345–354) includes Go examples demonstrating proper error context preservation. The security considerations (lines 357–362) correctly advise against exposing stack traces and internal messages in production, while emphasizing internal logging for debugging. These principles align with industry best practices for API security.
366-388: Component-specific guidelines provide actionable direction.The guidance for API Service, Sentinel, and Adapters (lines 368–387) is tailored to each component's role, specifying appropriate response formats, logging context, and the distinction between business logic failures and adapter errors. This structure enables consistent error handling across diverse HyperFleet subsystems.
415-518: Example error responses cover key scenarios comprehensively.The examples (validation, not found, version conflict, rate limit, internal server error) demonstrate proper use of Problem Details across different HTTP status codes and error categories. Each example includes trace_id for correlation and shows the full payload structure, making this section a practical reference for implementers.
rafabene
force-pushed
the
HYPERFLEET-378-error-model-standard
branch
from
c58c2dd to
7bbde35
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
hyperfleet/docs/error-model.md (1)
23-31: Unresolved: Remove or correct the inaccessible Go library reference.The previous review flagged this as a critical issue: the repository
github.com/openshift-hyperfleet/hyperfleet-errorsreturns a 404 and is not publicly accessible. Either remove the reference entirely, provide the correct repository path if it exists, or move this to internal/private documentation. Do not merge with a broken external link.
🧹 Nitpick comments (1)
hyperfleet/docs/error-model.md (1)
98-100: Add language identifiers to fenced code blocks.Fenced code blocks on lines 98 and 127 lack language specification. For format/pattern blocks, use
```textor```plaintext.🔎 Proposed fix
-``` +```text HYPERFLEET-{CATEGORY}-{NUMBER} -``` +```Apply the same fix at line 127 (and any other format-specification blocks without language tags).
Also applies to: 127-129
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
hyperfleet/components/api-service/api-versioning.mdhyperfleet/docs/error-model.md
🚧 Files skipped from review as they are similar to previous changes (1)
- hyperfleet/components/api-service/api-versioning.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
hyperfleet/docs/error-model.md
98-98: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
127-127: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (3)
hyperfleet/docs/error-model.md (3)
35-88: RFC 9457 foundation is well-structured.The RFC 9457 Problem Details section clearly differentiates standard fields from HyperFleet extensions, provides concrete examples, and establishes a solid foundation for the error model. The complete example response (lines 72–88) demonstrates proper integration of all fields.
102-179: HTTP status mapping and error code taxonomy are clear and unambiguous.The registered problem types (lines 102–117), error categories (lines 137–147), and HTTP status mapping policy (lines 175–178) are now explicit. The distinction between 400 (syntactic) and 422 (semantic) validation errors, and the consolidation of 502/503/504 under the SVC category, resolves the prior ambiguity. Well done.
182-528: Comprehensive error handling guidance with strong security posture.The validation error schemas (lines 186–248), constraint types (lines 250–262), error code catalog (lines 266–335), wrapping guidance (lines 339–355), security considerations (lines 357–363), component-specific guidelines (lines 366–388), logging integration (lines 391–411), and example responses (lines 415–518) are all well-executed. Security guidance to never expose stack traces and sanitize user input is explicit and appropriate. The examples demonstrate proper RFC 9457 compliance.
rafabene
force-pushed
the
HYPERFLEET-378-error-model-standard
branch
from
7bbde35 to
42ffb44
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
hyperfleet/docs/error-model.md (2)
23-31: Update Go library reference to indicate it is planned, not yet available.The reference implementation section states the library "is available at" a repository that does not yet exist. While the developer clarified it will be created as part of HYPERFLEET-415, the current wording may mislead readers. Update the language to indicate this is forthcoming.
🔎 Proposed update
### Reference Implementation -A shared Go library implementing this standard is available at: +A shared Go library implementing this standard is planned and will be available at: **Repository:** [github.com/openshift-hyperfleet/hyperfleet-errors](https://github.com/openshift-hyperfleet/hyperfleet-errors) +*(See [HYPERFLEET-415](https://issues.redhat.com/browse/HYPERFLEET-415) for implementation status)*
98-100: Add language specifications to fenced code blocks.Two code blocks lack language identifiers, which triggers markdown linter warnings (MD040). While the content is clear, adding language specifications improves consistency and helps syntax highlighting.
🔎 Proposed fix
### Type URI Format -``` +```plaintext https://api.hyperfleet.io/errors/{problem-type}And: ```diff ### Format -``` +```plaintext HYPERFLEET-{CATEGORY}-{NUMBER}</details> Also applies to: 127-129 </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: Organization UI **Review profile**: CHILL **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 7bbde35fd5ccf2fc69bb811f736d8e1e3374f3de and 42ffb443ec59ad6fef2ed2514051906461e258b9. </details> <details> <summary>📒 Files selected for processing (2)</summary> * `hyperfleet/components/api-service/api-versioning.md` * `hyperfleet/docs/error-model.md` </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🪛 markdownlint-cli2 (0.18.1)</summary> <details> <summary>hyperfleet/docs/error-model.md</summary> 98-98: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 127-127: Fenced code blocks should have a language specified (MD040, fenced-code-language) </details> </details> </details> <details> <summary>🔇 Additional comments (2)</summary><blockquote> <details> <summary>hyperfleet/components/api-service/api-versioning.md (2)</summary><blockquote> `85-102`: **RFC 9457 Problem Details integration is well-executed.** The error response format has been correctly updated to follow RFC 9457 with appropriate HyperFleet extensions (code, supported_versions). The Content-Type, structure, and fields align properly with the new error model standard. --- `184-184`: **Reference to error model documentation is properly added.** The new reference link to the HyperFleet Error Model and Codes Standard is correctly positioned and formatted, enabling readers to find the complete standard details. </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
rafabene
force-pushed
the
HYPERFLEET-378-error-model-standard
branch
from
42ffb44 to
d7ea5ce
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
hyperfleet/docs/error-model.md (1)
98-100: Add language specification to fenced code blocks for format examples.Lines 98 and 127 contain format pattern examples in fenced code blocks without language specification. While these are display patterns rather than executable code, adding an explicit language (e.g., ``
text) improves markdown linting and rendering consistency.🔎 Proposed fix
### Type URI Format -``` +```text https://api.hyperfleet.io/errors/{problem-type} -``` +```And similarly for line 127:
### Format -``` +```text HYPERFLEET-{CATEGORY}-{NUMBER} -``` +```
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
hyperfleet/components/api-service/api-versioning.mdhyperfleet/docs/error-model.md
🚧 Files skipped from review as they are similar to previous changes (1)
- hyperfleet/components/api-service/api-versioning.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
hyperfleet/docs/error-model.md
98-98: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
127-127: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (1)
hyperfleet/docs/error-model.md (1)
1-529: Comprehensive and well-structured error model documentation.The document successfully defines a clear, RFC 9457-compliant error standard for HyperFleet with appropriate level of detail. Key strengths:
- RFC 9457 alignment: Proper adoption with well-explained standard and extension fields (lines 35–88)
- Unambiguous HTTP mapping: Clear categorization of all client/server errors with explicit mapping policy for 400 vs 422 and service errors (lines 150–179)
- Comprehensive error taxonomy: 8 well-defined categories with consistent machine-readable codes (lines 121–336)
- Practical examples: Multiple realistic error response scenarios for validation, not-found, conflicts, and rate-limiting (lines 415–519)
- Security-first guidance: Clear do/don't on stack traces, internal errors, and input sanitization (lines 357–363)
- Component-specific guidance: Tailored advice for API Service, Sentinel, and Adapters with appropriate distinctions (lines 366–388)
- Forward-looking planning: Go library marked as "planned" with reference to HYPERFLEET-415, avoiding confusion (line 25)
Previous review feedback on HTTP status clarification and library references has been appropriately addressed.
Define standard error model and error codes for all HyperFleet
components (API, Sentinel, Adapters) following RFC 9457 Problem
Details for HTTP APIs.
Key additions:
- RFC 9457 Problem Details format with application/problem+json
- Error code format: HYPERFLEET-{CATEGORY}-{NUMBER}
- Error categories: VAL, AUT, AUZ, NTF, CNF, LMT, INT, SVC
- HTTP status code mapping rules
- Validation error detail structure
- Error wrapping and propagation guidelines
- Reference to shared library: github.com/openshift-hyperfleet/hyperfleet-errors
Also updated api-versioning.md to follow the new error standard.
Co-Authored-By: Claude <noreply@anthropic.com>
rafabene
force-pushed
the
HYPERFLEET-378-error-model-standard
branch
from
d7ea5ce to
448963f
Compare
hyperfleet/docs/error-model.md
Outdated
| "title": "Validation Error", | ||
| "status": 400, | ||
| "detail": "Cluster name is required", | ||
| "instance": "/api/hyperfleet/v1/clusters/requests/req-abc123" |
There was a problem hiding this comment.
I am thinking which one is better here request_id vs trace_id.
There was a problem hiding this comment.
Good question! Here's the difference:
request_id: A unique ID generated for each HTTP request, typically by the API gateway or servicetrace_id: A distributed tracing ID (OpenTelemetry/W3C Trace Context) that correlates a request across multiple services
The document currently uses trace_id because:
- It integrates with distributed tracing infrastructure (Jaeger, etc.)
- It allows correlation across API → Sentinel → Adapters
- It aligns with our Logging Specification
There was a problem hiding this comment.
But here the structure is using requests which may follow request_id. Maybe it deserve to be updated to get aligned and make it clear?
There was a problem hiding this comment.
Good catch! The instance field is the request path (per RFC 9457), not related to request_id. I'll update the examples to use a clearer pattern like /api/hyperfleet/v1/clusters without the /requests/ suffix to avoid confusion.
… errors Added explicit documentation clarifying that VAL-000 is reserved as the catch-all code for responses containing multiple validation errors, while specific codes (VAL-001, VAL-002, etc.) should be used for single-field errors. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
rafabene
force-pushed
the
HYPERFLEET-378-error-model-standard
branch
from
242196f to
1d1b5a3
Compare
2 participants
Summary
Defines a standard error model and error codes for all HyperFleet components (API, Sentinel, Adapters) to ensure consistent error handling across the platform.
Key additions:
code,message,detailsfieldsHYPERFLEET-{CATEGORY}-{NUMBER}(e.g.,HYPERFLEET-VAL-001)Acceptance Criteria
hyperfleet/docs/error-model.mdRelated
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.