Errors, Retries, and Timeouts

The Grounded SDK deliberately keeps failure behavior explicit. It does not silently swallow API or tracing errors.

@grounded/client

Client-side API failures surface as GroundedApiError.

try {
  await grounded.jobs.wait(job.id);
} catch (error) {
  if (error instanceof GroundedApiError) {
    console.error(error.status, error.requestId, error.body);
  }
  throw error;
}

What GroundedApiError Carries

• status
• requestId
• code
• details
• body

Retry Rules

The client retries:

• 429
• 5xx
• retryable network errors

It does not retry:

• 4xx auth failures
• validation errors
• timeouts caused by an aborted request

jobs.wait()

jobs.wait() throws if a job becomes:

• failed
• cancelled

It also throws on timeout if you provide timeoutMs.

@grounded/tracing

Tracing flushes retry:

• 429
• 5xx
• retryable network errors

If all retries fail, the batch is put back onto the in-memory queue and the error is thrown from flush() or shutdown().

Practical Patterns

Separate Product Errors From Telemetry Errors

try {
  await handleBusinessLogic();
} catch (error) {
  await trace.end({ status: 'error', error });
  throw error;
} finally {
  try {
    await tracing.flush();
  } catch (flushError) {
    console.error('grounded flush failed', flushError);
  }
}

Time-Bound Job Polling

await grounded.jobs.wait(job.id, {
  timeoutMs: 10 * 60_000,
  pollIntervalMs: 1_500,
});

Distinguish 401 vs 403

• 401: missing, invalid, expired, or revoked credentials
• 403: valid credentials, wrong kind, wrong scope, or wrong agent/tenant scope