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