001/*
002 * Copyright 2026 Revetware LLC.
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 */
016
017package com.revetsec;
018
019import javax.annotation.concurrent.Immutable;
020
021/**
022 * The broad kind of failure a {@link RevetsecException} reports.
023 * <p>
024 * Every {@code RevetsecException} has exactly one category. The documented category, reason, cause and response status
025 * determine its fixed temporary condition classification (see {@link RevetsecException#isTemporaryCondition()}).
026 * Only {@link #TRANSPORT} and {@link #REMOTE_ERROR} failures may be marked temporary; no category establishes
027 * whether earlier work had effects or is safe to replay.
028 *
029 * @author <a href="https://www.revetkn.com">Mark Allen</a>
030 * @since 1.0.0
031 */
032@Immutable
033public enum ErrorCategory {
034        /**
035         * The input could not be parsed, or it exceeded a configured limit: bad syntax, bad encoding, an oversized
036         * document or an unexpected structure. Never transient.
037         */
038        MALFORMED_INPUT,
039        /**
040         * The input was well formed but failed a security or protocol check, such as a signature, issuer, audience,
041         * lifetime or state check. Never transient.
042         */
043        VALIDATION_FAILURE,
044        /**
045         * The remote party answered with an error, such as an HTTP error status or a protocol error response. Transient
046         * only for HTTP 429 or 5xx, or OAuth {@code error=temporarily_unavailable}.
047         */
048        REMOTE_ERROR,
049        /**
050         * An external exchange or admitted operation did not yield ordinary successful output. Selected timeout, I/O
051         * and held-back-request conditions may be marked temporary. Interrupted threads and documented fixed commit
052         * outcome reasons retain their false classification; the category alone is no effect or replay verdict.
053         */
054        TRANSPORT,
055        /**
056         * Revetsec's configuration or runtime environment prevents the operation, in a way that could be discovered only
057         * at runtime, such as remote metadata that is incompatible with the configuration, or a default HTTP client that
058         * could not be started in this JVM. Never transient.
059         */
060        CONFIGURATION,
061        /**
062         * The input uses a feature that Revetsec does not support. Never transient.
063         */
064        UNSUPPORTED
065}