snowflake::ingest::streaming::ErrorDetail Class Referencefinal

The payload handed to an elastic-channel error handler (registered via StreamingIngestElasticChannel::SetErrorHandler()) when appends fail asynchronously. More...

#include <snowflake/ingest/streaming/elastic_channel.h>

Public Member Functions

 ErrorDetail (std::vector<AppendToken> append_tokens,StreamingIngestError error,std::optional<std::string> request_id,uint16_t retry_count)
const std::vector<AppendToken> & append_tokens () const noexcept
 The opaque, caller-supplied append tokens of the appends that failed with error().
const StreamingIngestError & error () const noexcept
 The error that failed the appends.
const std::optional<std::string> & request_id () const noexcept
 The Snowflake request ID of the request whose failure is being reported, or std::nullopt if this failure did not originate from a single identifiable request, e.g. channel invalidation or close.
uint16_t retry_count () const noexcept
 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.

Detailed Description

The payload handed to an elastic-channel error handler (registered via StreamingIngestElasticChannel::SetErrorHandler()) 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.

Member Function Documentation

append_tokens

const std::vector<AppendToken> & ErrorDetail::append_tokens() const
inlinenoexcept

The opaque, caller-supplied append tokens of the appends that failed with error().

Never empty; a token reused across appends appears once per failed append (not deduplicated). Read-only — the returned vector must not be modified.

Returns
the failing append tokens

error

const StreamingIngestError & ErrorDetail::error() const
inlinenoexcept

The error that failed the appends.

Returns
the error

request_id

const std::optional<std::string> & ErrorDetail::request_id() const
inlinenoexcept

The Snowflake request ID of the request whose failure is being reported, or std::nullopt 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 std::nullopt as "not available" rather than as information: one request ID covers a logical request and every retry of it (attempts are told apart by a retry count the SDK sends), so do not key application logic off this value. It is a support-escalation aid only.

Returns
the request ID, or std::nullopt

retry_count

uint16_t ErrorDetail::retry_count() const
inlinenoexcept

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 request_id() is absent the SDK failed the append itself: channel or client invalidation, a close, or an internal fault. Invalidation and close 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 request ID 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