Errors and locales

A GuildGate error result contains a stable code, user message, HTTP status, and retry information.

if (!result.ok) {
  console.error({
    requestId: result.meta.requestId,
    code: result.error.code,
    status: result.error.status,
    retryable: result.error.retryable,
  });
}

Result shape

{
  ok: false,
  error: {
    code: "revision_conflict",
    message: "The resource changed in another operation.",
    status: 409,
    retryable: false,
    details: {
      expected: 4,
      current: 5,
    },
  },
  meta: {
    requestId: "...",
    locale: "en",
  },
}

details must contain only client-safe fields. Do not return SQL, stacks, tokens, or raw driver errors.

Locale resolution

The request locale is narrowed to a supported value; unsupported input falls back to the configured default. The package includes tr and en messages.

locale: {
  default: "tr",
  messages: {
    tr: {
      maintenance: "Panel kısa süreli bakımda.",
    },
  },
}

An override key should match the stable error code. Keep code and display text separate; do not bind frontend logic to translated prose.

Important 1.1 error areas

• deadline and timeout
• idempotency conflict
• idempotency reservation loss
• revision conflict
• lock or lease acquisition
• malformed audit cursor
• origin or CSRF rejection
• required, expired, or revoked session
• maintenance or policy block
• realtime subscription and message limits

Use the installed version's errors.d.ts and runtime result for the complete code list.

Retry decision

retryable: true does not mean the client should retry immediately without bounds. A client should:

• honor Retry-After or rate metadata
• apply exponential backoff
• preserve the same idempotency key
• avoid retrying authorization failures that need user action

Post-commit issues

A successful result may include meta.postCommitIssues. This does not mean the domain write failed. The UI should show the committed state while the server handles cache, realtime, or audit retry paths.

Request ID

requestId may be displayed as a support code. Carry the same ID through application logs, traces, and audit records to connect the request chain.

HTTP adapter

Official adapters handle status and cookie metadata. A custom adapter must:

• write status only once
• preserve the error code
• serialize the localized message safely
• apply clearSessionCookie and replacement tokens
• avoid exposing the server error cause