Package org.elasticsearch.xpack.esql.datasources.spi

Class ExternalUnavailableException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

org.elasticsearch.ElasticsearchException

org.elasticsearch.xpack.esql.core.QlException

org.elasticsearch.xpack.esql.datasources.spi.ExternalException

org.elasticsearch.xpack.esql.datasources.spi.ExternalUnavailableException

All Implemented Interfaces:

Serializable, Writeable, ToXContent, ToXContentFragment

public final class ExternalUnavailableException
extends ExternalException

A retryable transport failure talking to the remote store backing an external data source — the store returned a 5xx, throttled us, or the connection timed out / was reset. Maps to 503 Service Unavailable: the read might succeed on retry, so it is neither a permanent client error nor a cluster bug.

Permanent transport outcomes (object not found, a malformed response) are not raised here; those are client-class and surface as ExternalClientException.

Carries a throttling() flag so the retry layer can tell a back-pressure response (429 / 503 — slow down) from a plain transient failure (500 / 502 / 504): throttling failures get a higher retry budget and feed the cross-request adaptive backoff. The provider sets it from the status code (it has the concrete type); the retry policy keys on the typed exception, never on message text.

See Also:

• Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface org.elasticsearch.xcontent.ToXContent

ToXContent.DelegatingMapParams, ToXContent.MapParams, ToXContent.Params

Nested classes/interfaces inherited from interface org.elasticsearch.common.io.stream.Writeable

Writeable.Reader<V>, Writeable.Writer<V>

Field Summary

Fields inherited from class org.elasticsearch.ElasticsearchException

REST_EXCEPTION_SKIP_CAUSE, REST_EXCEPTION_SKIP_STACK_TRACE, REST_EXCEPTION_SKIP_STACK_TRACE_DEFAULT, STACK_TRACE

Fields inherited from interface org.elasticsearch.xcontent.ToXContent

EMPTY, EMPTY_PARAMS

Constructor Summary

Constructors

Constructor	Description
ExternalUnavailableException(boolean throttling, String message, Object... args)
ExternalUnavailableException(boolean throttling, Throwable cause, String message, Object... args)
ExternalUnavailableException(String message, Object... args)
ExternalUnavailableException(String message, Throwable cause)
ExternalUnavailableException(Throwable cause, String message, Object... args)

Method Summary

Modifier and Type	Method	Description
static boolean	isRetryableStatus(int httpStatus)	Whether an HTTP status returned by a remote store should be treated as a retryable transport failure (a 503 on our side) rather than a client-class error.
static boolean	isThrottlingStatus(int httpStatus)	Whether a retryable status is specifically a throttling / back-pressure signal (429 or 503) as opposed to a plain transient failure (500 / 502 / 504).
RestStatus	status()
boolean	throttling()	true if this represents a throttling / slow-down response (HTTP 429 or 503), which a retry policy may treat differently (longer budget, adaptive backoff) from a plain transient transport fault.

Methods inherited from class org.elasticsearch.ElasticsearchException

addBodyHeader, addBodyHeader, addHttpHeader, addHttpHeader, addMetadata, addMetadata, failureFromXContent, fromXContent, generateFailureXContent, generateThrowableXContent, generateThrowableXContent, getBodyHeader, getBodyHeaderKeys, getBodyHeaders, getDetailedMessage, getExceptionName, getExceptionName, getExceptionName, getHttpHeader, getHttpHeaderKeys, getHttpHeaders, getId, getIndex, getMetadata, getMetadata, getMetadataKeys, getResourceId, getResourceType, getRootCause, getShardId, guessRootCauses, guessRootCauses, innerFromXContent, innerToXContent, isRegistered, isTimeout, metadataToXContent, readException, readException, readStackTrace, setIndex, setIndex, setResources, setShard, toString, toXContent, toXContent, unwrapCause, writeException, writeStackTraces, writeTo, writeTo

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.elasticsearch.xcontent.ToXContentFragment

isFragment

Constructor Details

ExternalUnavailableException

public ExternalUnavailableException(String message,
 Throwable cause)

ExternalUnavailableException

public ExternalUnavailableException(Throwable cause,
 String message,
 Object... args)

ExternalUnavailableException

public ExternalUnavailableException(String message,
 Object... args)

ExternalUnavailableException

public ExternalUnavailableException(boolean throttling,
 Throwable cause,
 String message,
 Object... args)

ExternalUnavailableException

public ExternalUnavailableException(boolean throttling,
 String message,
 Object... args)

Method Details

status

public RestStatus status()

Overrides:

status in class ElasticsearchException

throttling

public boolean throttling()

true if this represents a throttling / slow-down response (HTTP 429 or 503), which a retry policy may treat differently (longer budget, adaptive backoff) from a plain transient transport fault.

isRetryableStatus

public static boolean isRetryableStatus(int httpStatus)

Whether an HTTP status returned by a remote store should be treated as a retryable transport failure (a 503 on our side) rather than a client-class error. Limited to the transient codes a retry can plausibly clear: 429 (throttling), 500, 502, 503 and 504. Other 5xx codes are permanent — e.g. 501 (Not Implemented) and 505 (HTTP Version Not Supported) mean the operation is unsupported, not temporarily unavailable — so they, like 4xx, fall through to a client-class 400.

isThrottlingStatus

public static boolean isThrottlingStatus(int httpStatus)

Whether a retryable status is specifically a throttling / back-pressure signal (429 or 503) as opposed to a plain transient failure (500 / 502 / 504). Used to set throttling() at the classification site.