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
400	`no_sources`	`sources` is empty and `allowUngrounded` is false.
400	`sources_too_large`	`sources` text exceeds the character budget (~100k).
400	`invalid_request`	Malformed body — missing `model`/`messages`, bad JSON.
401	`invalid_key`	Missing or rejected API key.
402	`insufficient_quota`	Billing / quota exhausted (from the gateway).
429	`rate_limited`	Rate limit hit (from the gateway).
502	`extraction_failed`	The model returned an unparseable structure after a retry.
5xx	`gateway_error`	Upstream gateway/model failure.

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 Python SDK