Error shapes

Every non-2xx response from the Warpweb API returns a JSON body with at least an error string. Depending on the endpoint and the failure mode, the body may carry one or more optional fields that give the caller a recovery path or machine-readable context.

This page is the canonical reference for the envelope. Per-endpoint reference pages document which optional fields THAT endpoint can emit; this page documents what each field means whenever you encounter it.

Implementation note. The current implementation emits a handful of envelope variants depending on which handler ran; we’re consolidating over time. Until then, write your error-handling code defensively: always read error; check for hint / reason / suggestion / quota before using them.

Canonical envelope

{
  "error": "Human-readable summary of what went wrong.",
  "hint": "Optional. Recovery path or context — surface to your operator.",
  "reason": "Optional. Machine-readable code for branching, OR the human-readable reason on /revisions 422.",
  "suggestion": "Optional. An in-scope alternative the caller can try.",
  "quota": {
    "used": 5,
    "limit": 5,
    "resetDescription": "resets at midnight UTC"
  }
}

reason has two meanings

The reason field is overloaded across surfaces. Branch by where you’re reading it from:

This asymmetry is documented on POST /v1/sites/:id/revisions. For code that reads both surfaces, branch by surface first, then by reason.

Status code map

Endpoints that emit non-standard fields

Use this table to jump to the per-endpoint page when you’re handling a specific 4xx/5xx body shape.

Defensive parsing pattern

type WarpwebError = {
  error: string
  hint?: string
  reason?: string
  reason_detail?: string
  suggestion?: string
  quota?: { used: number; limit: number; resetDescription: string }
  queue_full?: boolean
  internal_error?: string
}
 
async function callWarpweb(input: RequestInfo, init?: RequestInit) {
  const res = await fetch(input, init)
  if (res.ok) return res.json()
 
  const body: WarpwebError = await res.json().catch(() => ({ error: `HTTP ${res.status}` }))
 
  // Prefer the most specific recovery path the server offered.
  const userMessage = body.suggestion ?? body.hint ?? body.error
 
  throw Object.assign(new Error(userMessage), {
    status: res.status,
    body,
  })
}

Related

• API Reference → Common conventions → Errors — the status-code table.
• Authentication → Rate limits — what triggers 429s and how the quota shape is composed.