Request traces: why did this request fail?

A request passes several checks before it reaches your data: sign-in, the caller's access to the project, their team role, rate limits, app attestation, plan limits, Guard policies, and in the database, row-level security and privileges. When one of them says no — or a service fails — Monitor › Request traces shows which one, the reason, and what to do.

#The trace id

The SDKs send a W3C traceparent with every call (all retries of one call share it) and put the trace id on errors; every response also carries it as X-Request-ID.

try {
  await sov.data.sql('insert into orders (total) values ($1)', [42])
} catch (e) {
  if (e instanceof SovariaError) {
    console.log(e.traceId)            // 4bf92f3577b34da6a3ce929d0e0e4736
    const why = await sov.api.traces.get({ traceId: e.traceId! })   // project team only
    why.explanation  // { verdict: 'denied', by: 'Guard policy', reason: "Guard denied INSERT on 'orders' …", hint: '…' }
  }
}

#What it can tell you

• Refusals (401, 403, 409, 422, 429) and failures (5xx) are recorded; successful requests are not stored.
• Only refusals of signed-in callers of your project are stored for it — anonymous noise never lands in your traces.
• Only your project team can read its traces (not app users or the anon key), and another project's trace id answers like one that doesn't exist.
• Messages are stored as the caller saw them, with tokens and secrets scrubbed; request and response bodies are never stored.

#How long traces are kept