Errors and retries

Query and mutation results

Every awaitable Athena.js operation resolves to an AthenaResult<T>.

const result = await athena.from("users").select("id, email");

if (result.error) {
  console.error(result.error.message);
  console.error(result.error.code, result.error.kind, result.error.status);
  console.error(result.error.endpoint, result.error.requestId);
  return;
}

The important change from older examples is that result.error is now a structured object, not a plain string.

Structured AthenaResult.error

Failed results expose a normalized error with fields such as:

• message
• code
• athenaCode
• gatewayCode
• kind
• category
• retryable
• details
• hint
• status
• statusText
• table
• operation
• endpoint
• method
• requestId

errorDetails still exists on AthenaResult as a compatibility alias for gateway metadata, but new code should prefer the richer fields already placed on error.

React hook

useAthenaGateway() is different from AthenaResult:

• AthenaResult.error is structured
• useAthenaGateway().error is still a hook-level string | null

The hook stores request state, while builder calls return normalized result envelopes.

insertGateway, updateGateway, deleteGateway, and rpcGateway still throw on failure, so wrap them in try/catch when you call the hook directly.

Reliability helpers

Athena.js exports helpers for the common service-layer branches:

• isOk
• unwrap
• unwrapRows
• unwrapOne
• requireSuccess
• requireAffected
• normalizeAthenaError
• coerceInt
• assertInt
• withRetry

Example:

import { isOk, unwrapRows, withRetry } from "@xylex-group/athena";

const result = await withRetry({ retries: 2 }, () =>
  athena.from("users").select("id, email"),
);

if (!isOk(result)) {
  throw new Error(result.error?.message ?? "Athena request failed");
}

const rows = unwrapRows(result);

Full signatures live in the API reference.

Related

• Overview
• API reference