Errors

Every error is returned as JSON with a stable type you can branch on:

{ "error": { "type": "no_sources", "message": "provide sources, or set allow_ungrounded=true" } }

HTTP error table

HTTP	`type`	When	Recovery
400	`no_sources`	`sources` is empty and `allowUngrounded` is false.	Pass `sources`, or set `allowUngrounded: true` to get a flagged plain answer (`grounded: false`).
400	`sources_too_large`	`sources` text exceeds the character budget (~100k chars).	Chunk your sources and send fewer/smaller ones per call (e.g. retrieve top-k before calling).
400	`invalid_request`	Malformed body — missing `model`/`messages`, bad JSON.	Fix the request shape: `model` + `messages` are required and the body must be valid JSON.
401	`invalid_key`	Missing or rejected API key.	Check the `MAXMODEL_KEY`; regenerate the token in the maxmodel.com console if needed.
402	`insufficient_quota`	Billing / quota exhausted (from the gateway).	Top up the account balance / check billing in the console. Not a retry — the call won’t succeed until funded.
429	`rate_limited`	Rate limit hit (from the gateway).	Back off and retry with exponential backoff (e.g. 1s, 2s, 4s + jitter).
502	`extraction_failed`	The model returned an unparseable structure after a retry.	Retry; if it persists, reduce prompt/source complexity or use a more capable model. (The model couldn’t emit valid claim JSON — this is honest, fail-loud degradation, not silent ungrounded text.)
5xx	`gateway_error`	Upstream gateway/model failure.	Transient — retry with backoff.

Key validation and quota/rate limits are enforced by the gateway and surfaced here with the matching status, so you handle them the same way you handle any gateway error today.

Typed errors in the SDK

The SDK throws typed, catchable errors. Branch on the class or on .type / .status:

import {
  MaxModel,
  MaxModelError,
  AuthError,        // 401
  QuotaError,       // 402
  RateLimitError,   // 429
  NoSourcesError,   // 400 no_sources
  ExtractionError,  // 502 extraction_failed
  GatewayError,     // 5xx / network
} from 'maxmodel'
 
const mx = new MaxModel({ apiKey: process.env.MAXMODEL_KEY! })
 
try {
  const out = await mx.verified.create({ /* ... */ } as any)
} catch (e) {
  if (e instanceof NoSourcesError) {
    // you forgot sources, or set allowUngrounded
  } else if (e instanceof RateLimitError) {
    // back off and retry
  } else if (e instanceof MaxModelError) {
    console.error(e.type, e.status, e.message)
  } else {
    throw e
  }
}

Every SDK error extends MaxModelError, which carries:

class MaxModelError extends Error {
  type: string   // e.g. 'invalid_key'
  status: number // HTTP status, or 0 for client/network errors
}

How verification works Benchmarks