Package com.snowflake.ingest.streaming

Interface ErrorDetail

public interface ErrorDetail
The payload handed to an elastic-channel error handler (registered via SnowflakeStreamingIngestElasticChannel.setErrorHandler(java.util.function.Consumer<com.snowflake.ingest.streaming.ErrorDetail>)) when appends fail asynchronously.

Delivered once per failure event and carries the caller-supplied append tokens of every append that failed together under a common error — a whole server-ack error batch, or every tracked in-flight append on channel invalidation.

Implemented by the SDK, never by callers: handlers only read this type, so new accessors can be added over time without breaking them.

  • Method Summary

    Modifier and Type
    Method
    Description
    Iterable<Object>
    getAppendTokens()
    The opaque, caller-supplied append tokens of the appends that failed with getError().
    SFException
    getError()
    The error that completed the failing appends exceptionally.
    String
    getRequestId()
    The Snowflake requestId of the request whose failure is being reported, or null if this failure did not originate from a single identifiable request — e.g.
    int
    getRetryCount()
    How many retries the failing request had already made: 0 when the first attempt failed, N when the SDK retried N times before giving up.

  • Method Details

    • getAppendTokens

      Iterable<Object> getAppendTokens()
      The opaque, caller-supplied append tokens of the appends that failed with getError(). Never empty; a token reused across appends appears once per failed append (not deduplicated). Read-only — the returned iterable must not be modified.
      Returns:
      the failing append tokens

    • getError

      SFException getError()
      The error that completed the failing appends exceptionally.
      Returns:
      the error

    • getRequestId

      @Nullable String getRequestId()
      The Snowflake requestId of the request whose failure is being reported, or null if this failure did not originate from a single identifiable request — e.g. channel invalidation or close. Useful when escalating a failure to Snowflake support.

      Treat null as "not available" rather than as information: one requestId covers a logical request and every retry of it — attempts are told apart by a retryCount the SDK sends — so do not key application logic off this value. It is a support-escalation aid only.

      Returns:
      the requestId, or null

    • getRetryCount

      int getRetryCount()
      How many retries the failing request had already made: 0 when the first attempt failed, N when the SDK retried N times before giving up.

      This answers one question: could the SDK have applied this rowset more than once? It does not answer whether the rows reached the table at all. A retry re-sends the same rowset, and the SDK retries any failure it cannot prove the server rejected -- a timeout, a transport error or a 5xx may mean the rows were never processed, or that they were processed and only the response was lost.

      • 0 -- the SDK sent this rowset at most once, so it cannot have duplicated it.
      • > 0 -- the SDK sent it more than once and an earlier attempt may already have been applied, so the rows may appear in the table more than once even though the append is being reported as failed. Reconcile or de-duplicate downstream if you need exactly-once.

      Conservative by design: every re-send counts, including an authentication refresh, which is rejected before the rows are processed and so cannot have duplicated anything. A non-zero count therefore means "a duplicate is possible", not "a duplicate happened" -- the SDK does not distinguish the two, and over-reporting is the safe direction here.

      0 is not a statement that the rows are absent. Two ways a failed append can have landed anyway while reporting 0:

      • The SDK sent it once and failed only on the response -- a body it could not parse, say -- after Snowflake had already accepted the rows.
      • The failure did not come from a request at all. When getRequestId() is null the SDK failed the append itself: channel or client invalidation, a close or drop, an internal fault, or a payload it could not serialize. All but the last fail every append still in flight, including one whose request had already gone to Snowflake and may still be applied after this handler returns. Such a failure reports 0 because there was no attempt to count, not because anything was rejected.

      The SDK cannot resolve either case for you: an append has to be failed when the channel goes away, and an in-flight request's outcome is not known at that point. Reconcile against the table if you need to know whether the rows landed.

      Together with the requestId this identifies the exact attempt server-side: the SDK sends both as the requestId and retryCount query params on every request.

      Returns:
      the number of retries, 0 when there was no retry or no originating request