Record Class UpstreamFailure

java.lang.Object

java.lang.Record

ai.redouble.nucleo.harness.errors.http.UpstreamFailure

Record Components:

statusCode - HTTP status, or 0 when the request never got a response

service - the upstream the limiter is protecting, e.g. PubMed

detail - the service's own error text, including endpoint and response body

retryAfterSeconds - the server's own instruction, or 0 when it did not give one

public record UpstreamFailure(int statusCode, String service, String detail, int retryAfterSeconds)
extends Record

What an upstream service actually said when a request failed: the HTTP status and the response detail, carried together so a RateLimiter can record them.

A limiter reacting to upstream pressure needs more than a retry hint. It records this alongside its throttle and circuit state and quotes it back when a circuit opens, so a tool that has been disabled names the upstream response responsible instead of leaving it to be reconstructed from surrounding log lines.

Since:

0.1 (2026-08-17)

Author:

Andrey Santrosyan

Constructor Summary

Constructors

Constructor	Description
UpstreamFailure(int statusCode, String service, String detail, int retryAfterSeconds)	Creates an instance of a UpstreamFailure record class.

Method Summary

Modifier and Type	Method	Description
String	detail()	Returns the value of the detail record component.
final boolean	equals(Object o)	Indicates whether some other object is "equal to" this one.
static UpstreamFailure	from(ExternalServiceException e)	Reads what the server actually said, wherever it sits in the cause chain.
final int	hashCode()	Returns a hash code value for this object.
int	retryAfterSeconds()	Returns the value of the retryAfterSeconds record component.
String	service()	Returns the value of the service record component.
int	statusCode()	Returns the value of the statusCode record component.
String	summary()	Compact one-line form for log lines, event reasons, and LLM-facing error messages.
final String	toString()	Returns a string representation of this record class.

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Details

UpstreamFailure

public UpstreamFailure(int statusCode,
 String service,
 String detail,
 int retryAfterSeconds)

Creates an instance of a UpstreamFailure record class.

Parameters:

statusCode - the value for the statusCode record component

service - the value for the service record component

detail - the value for the detail record component

retryAfterSeconds - the value for the retryAfterSeconds record component

Method Details

from

public static UpstreamFailure from(ExternalServiceException e)

Reads what the server actually said, wherever it sits in the cause chain. A status exists only when the failure was raised from an HTTP response, an HttpErrorResponse carrier; a tool that wrapped that carrier with its service and step (LLMReadableCheckedException.wrapWithContext) still has it as a cause, so the status and the server's detail are read off the first carrier in the chain, and the retry-after off the first UpstreamThrottleException. Both are 0 only when no carrier is anywhere in the chain: a transport failure - connection refused, read timeout, unparseable body - genuinely has no status, and 0 records that rather than guessing. The service is the outermost exception's, the one the tool named.

summary

public String summary()

Compact one-line form for log lines, event reasons, and LLM-facing error messages.

toString

public final String toString()

Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.

Specified by:

toString in class Record

Returns:

a string representation of this object

hashCode

public final int hashCode()

Returns a hash code value for this object. The value is derived from the hash code of each of the record components.

Specified by:

hashCode in class Record

Returns:

a hash code value for this object

equals

public final boolean equals(Object o)

Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with the compare method from their corresponding wrapper classes.

Specified by:

equals in class Record

Parameters:

o - the object with which to compare

Returns:

true if this object is the same as the o argument; false otherwise.

statusCode

public int statusCode()

Returns the value of the statusCode record component.

Returns:

the value of the statusCode record component

service

public String service()

Returns the value of the service record component.

Returns:

the value of the service record component

detail

public String detail()

Returns the value of the detail record component.

Returns:

the value of the detail record component

retryAfterSeconds

public int retryAfterSeconds()

Returns the value of the retryAfterSeconds record component.

Returns:

the value of the retryAfterSeconds record component