001/*
002 * Copyright © 2025 CUI-OpenSource-Software (info@cuioss.de)
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package de.cuioss.http.client.result;
017
018/**
019 * Essential HTTP error codes for resilient operations.
020 * Provides minimal but sufficient error classification focused on actionable distinctions
021 * needed for retry logic, monitoring, and error handling.
022 *
023 * <h2>Design Principles</h2>
024 * <ul>
025 *   <li>Only includes error codes that require different handling</li>
026 *   <li>Focuses on operational concerns rather than detailed HTTP semantics</li>
027 *   <li>Enables effective retry and fallback strategies</li>
028 * </ul>
029 *
030 * <h2>Usage Pattern</h2>
031 * <pre>
032 * HttpResultObject&lt;String&gt; result = httpHandler.load();
033 * if (!result.isValid()) {
034 *     result.getErrorCode().ifPresent(code -> {
035 *         if (code.isRetryable()) {
036 *             scheduleRetry();
037 *         } else {
038 *             useFallback();
039 *         }
040 *     });
041 * }
042 * </pre>
043 *
044 * @author Implementation for HTTP operations
045 * @see HttpResultObject
046 * @see de.cuioss.uimodel.result.ResultDetail
047 * @since 1.0
048 */
049public enum HttpErrorCategory {
050
051    // === Network Errors (Retryable) ===
052
053    /**
054     * Network connectivity problems - timeouts, connection failures, etc.
055     * Covers all transient network issues that may resolve with retry.
056     */
057    NETWORK_ERROR,
058
059    /**
060     * Server-side errors (HTTP 5xx).
061     * Remote server problems that may be transient.
062     */
063    SERVER_ERROR,
064
065    /**
066     * Client-side errors (HTTP 4xx).
067     * Request problems that typically require configuration changes.
068     */
069    CLIENT_ERROR,
070
071    // === Content Errors (Non-retryable) ===
072
073    /**
074     * Response content is invalid or unparseable.
075     * Covers all content validation failures including empty responses,
076     * malformed JSON, invalid JWKS, invalid well-known configs, etc.
077     */
078    INVALID_CONTENT,
079
080    /**
081     * Configuration or setup errors.
082     * Invalid URLs, missing settings, SSL issues, authentication problems.
083     * Typically requires human intervention to resolve.
084     */
085    CONFIGURATION_ERROR;
086
087    /**
088     * Determines if this error code represents a retryable condition.
089     * Only network and server errors are typically transient and worth retrying.
090     *
091     * @return true if the error condition is typically retryable
092     */
093    public boolean isRetryable() {
094        return this == NETWORK_ERROR || this == SERVER_ERROR;
095    }
096
097}