Errors

SDK calls raise a Seal error. Requests inside a session get refused in the protocol's own terms: an HTTP status, a Postgres error or a Redis reply. Both use the same thirteen codes. The caller gets only the code and a fixed message; the full reason goes to your telemetry.

Every error#

Retrying won't help with a "No" until something changes. Only Unavailable and SessionExpired are retryable.

Catching errors#

Every SDK error carries a code, a retryable flag and a message.

import os, seal

try:
    with seal.session(os.environ["OPENAI_API_BLOB"]) as s:
        ...
except seal.Expired:
    # Seal the secret again and deploy the new blob
    ...
except seal.SealError as e:
    print(e.code, e.retryable, e.message)
    raise

import { Client, Expired, SealError } from "@sealzone/sdk";

const seal = await Client.fromEnv();
try {
  const s = await seal.session(process.env.OPENAI_API_BLOB, { kind: "http" });
} catch (e) {
  if (e instanceof Expired) {
    // Seal the secret again and deploy the new blob
  } else if (e instanceof SealError) {
    console.error(e.code, e.retryable, e.message);
  }
  throw e;
}

s, err := client.Session(ctx, blob, seal.WithKind(seal.KindHTTP))
if errors.Is(err, seal.ErrExpired) {
	// Seal the secret again and deploy the new blob
}
var se *seal.Error
if errors.As(err, &se) {
	log.Println(se.Code, se.Retryable(), se.Message)
}

match seal.session(&blob).http().await {
    Ok(s) => { /* use s.url(), s.key() */ }
    Err(e) if e.code() == seal::ErrorCode::Expired => {
        // Seal the secret again and deploy the new blob
    }
    Err(e) => eprintln!("{:?} retryable={}: {e}", e.code(), e.code().retryable()),
}

Refusals inside a session#

Your app talks to its usual client library, so refusals arrive in that protocol's format. Anything the upstream sends, its own errors included, passes through unchanged apart from key masking.

HTTP#

The enclave answers with a status and a JSON body. The seal_error field marks the refusal as Seal's, not the upstream's.

{
  "seal_error": "policy_denied",
  "message": "the request is outside the blob's policy"
}

The message is one of a fixed set:

"No Seal credential" almost always means the library didn't send the stand-in key. Pass s.key where it expects its API key.

Postgres#

The error text starts with seal: and ends with the code, such as seal: … (policy_denied).

Redis#

A command the blob doesn't allow gets -NOPERM seal policy_denied: …, and the connection stays open. When the session ends, the client gets -ERR seal <code>: … and the connection closes.

Finding the reason in telemetry#

A refused session shows up as a Refused entry. A refused request shows up as a denied Request entry with the code. Filter the console's Telemetry page by app, identity, blob or event, or run seal telemetry --since 1h. Entries never hold the secret, bodies or upstream text.