Errors

Error handling on this API has a wrinkle worth knowing about before you write your client. There are two body formats, and one class of endpoint returns failures with a 200.

Two formats

Plain text — Content-Type: text/plain; charset=utf-8, with a trailing newline. Used by authentication failures, method-not-allowed, and all manifest errors:

manifest: not found

JSON — Content-Type: application/json. Used by prepare-write, cap rejections, and rate limiting:

{ "error": "redundancy 1.400 < 1.5" }

A robust client checks the content type, or simply tries to parse JSON and falls back to the raw text:

async function readError(res: Response): Promise<string> {
  const text = await res.text()
  try {
    const parsed = JSON.parse(text)
    return parsed.error ?? text
  } catch {
    return text.trim()
  }
}

The 200-with-an-error case

async function call(method: string, path: string, body?: unknown) {
  const res = await signedFetch(method, path, body)
  const text = await res.text()

  if (!res.ok) throw new TesseraError(res.status, await readErrorFrom(text))

  const parsed = text ? JSON.parse(text) : null
  if (parsed && typeof parsed === 'object' && 'error' in parsed) {
    throw new TesseraError(res.status, parsed.error) // 200, but not a success
  }
  return parsed
}

Status codes

Manifest error strings

Manifest errors arrive as plain text with these exact bodies. Match on them if you need to branch:

Authentication errors

All 401, all plain text. See Authentication § failure modes for what each one indicates and how to debug signature mismatch.

missing auth params · invalid validUntil · signature expired
invalid credential  · unknown credential · invalid signature · signature mismatch

Rate limiting

HTTP/1.1 429 Too Many Requests
Retry-After: 5

{"error":"rate limited","retryAfter":5}

Honour Retry-After. Provisioning has its own limit with a distinct body:

{ "error": "rate limited: max 5 keys per hour" }

See Limits.

A retry policy that behaves

const RETRYABLE = new Set([429, 500, 502, 503, 504])

async function withRetry<T>(fn: () => Promise<T>, attempts = 5): Promise<T> {
  let lastErr: unknown
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn()
    } catch (err) {
      lastErr = err
      const status = (err as TesseraError).status
      if (!RETRYABLE.has(status)) throw err            // 4xx: retrying cannot help

      const retryAfter = (err as TesseraError).retryAfter
      const backoff = retryAfter
        ? retryAfter * 1000
        : Math.min(2 ** i * 250, 8000) + Math.random() * 250   // jitter matters
      await new Promise((r) => setTimeout(r, backoff))
    }
  }
  throw lastErr
}

Two things this gets right that naive retry loops do not: it refuses to retry 4xx responses, where the answer will not change, and it adds jitter, so a fleet of clients recovering from an outage does not synchronise into a thundering herd.

Errors worth special handling

Transfer errors from the CLI

Before each upload or download, tessera checks that enough storage providers are reachable and funded, and names the cause when a transfer cannot run. These are the messages and what to do:

Read-only requests retry on dropped connections (a bare EOF, a reset) before failing. Error output never includes URL query strings, which carry request signatures.