Errors

All errors - including unexpected server errors - return:

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}

Some errors add context fields (details, limit, tokenBalance, resetAt, …). The code values are stable; branch on them, not on messages.

Branch on code, never on error. The error string is prose and it changes: on 402 INSUFFICIENT_TOKENS and 403 STARTER_LIMIT_REACHED for accounts on the free plan it now runs to a sentence or two and includes a URL. code and the HTTP status did not move and will not.

The `upsell` object

402 INSUFFICIENT_TOKENS and 403 STARTER_LIMIT_REACHED may carry an extra upsell object. Free accounts receive the founder_report offer; a paid, non-regional account with no deep credits may receive a scan_pack top-up on 402. It is additive and optional, absent on batch items, and may be absent at any time, so treat its presence as a bonus, never as a contract:

{
  "error": "No deep credits on this account. The Founder Report unlocks ...",
  "code": "INSUFFICIENT_TOKENS",
  "tokenBalance": 0,
  "upsell": {
    "offer": "founder_report",
    "price": "$29 one-time",
    "guarantee": "14-day satisfaction guarantee",
    "url": "https://preuve.ai/pricing?src=agent_api&utm_source=agent_api&utm_medium=agent",
    "locked": ["Market size (TAM/SAM/SOM)", "Up to 15 competitors with funding and weak spots"],
    "note": "One relay-ready sentence saying the same thing."
  }
}

The same object also appears on GET /api/agent/analyses/:id when a starter scan owned by a free account has finished. note is written to be relayed to a human as-is. guarantee appears only on offer: "founder_report". It is omitted from scan_pack top-ups. url is tagged with the door the request came through: utm_source=agent_api for direct x-preuve-key calls like the one above, utm_source=mcp through the hosted MCP server. An error carrying upsell is a quota or billing answer, never a bad key. If you are an agent, do not send the user to the API-keys panel for one.

Common codes

HTTP	Code	Meaning	What to do
400	`INVALID_MODULES`	Unknown or malformed `modules` array	Fix the module names
400	`INVALID_FOUNDER_PROFILE`	Missing/invalid `founderProfile` for `founderFit`	Fix the fields listed in `details`
400	`INVALID_ANALYSIS_ID`	Malformed run/report id	Use the id returned by create
401	(auth codes)	Missing, malformed, unknown or revoked key	Check Authentication
402	`INSUFFICIENT_TOKENS`	Deep scan with no quota and no tokens	Top up or use `scanType: "starter"`
403	`MODULES_REQUIRE_DEEP`	Modules requested on a non-deep report	Run a deep scan first
403	`STARTER_LIMIT_REACHED`	Starter scan allowance exhausted (free/regional)	Wait for reset or run deep
429	`FAIR_USE_LIMIT`	Paid account hit the starter fair-use ceiling	Contact support to lift it
404	`ANALYSIS_NOT_FOUND`	Unknown id, or the run belongs to another account	Check the id
409	`ANALYSIS_NOT_COMPLETE`	Run still processing	Keep polling
409	`ENRICHMENT_NOT_COMPLETE`	Export requested before enrichment	Call enrich, poll, retry
409	`MODULE_ALREADY_GENERATED`	Per-module cap reached (one success per report)	Read the payload from the export
413	`PAYLOAD_TOO_LARGE`	Body over the size limit	Trim the request
422	`ANALYSIS_FAILED`	The analysis itself failed	Create a new run
429	`RATE_LIMITED`	Per-route rate limit hit	Back off and retry
429	`CONCURRENT_LIMIT_REACHED`	Too many analyses in flight (3 free / 2 deep)	Wait for one to finish, re-POST the same `clientRunId`
429	`DAILY_LIMIT_REACHED`	Rolling 24h creation ceiling	Retry after `resetAt`
429	`REGEN_LIMIT_REACHED`	Founder Fit lifetime cap on this report	No retry - cap is final
503	`INSUFFICIENT_TIME_BUDGET`	Inline module refused to start late in the request	Retry the same enrich call
503	`SERVICE_DISABLED` / `GENERATION_DISABLED` / `POD_DISABLED`	Feature temporarily off	Retry later
502	`ENQUEUE_FAILED`	Background dispatch failed	Retry; nothing was consumed
500	`INTERNAL_ERROR`	Unexpected server error	Retry with backoff

Retry-After

A 429 RATE_LIMITED carries a Retry-After response header: whole seconds until the limiter’s window rolls over. Those windows are fixed one-minute buckets, so the number is exact, not an estimate - waiting that long is enough, and retrying sooner is not.

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

The JSON body is unchanged; keep branching on code. The quota-shaped 429s (CONCURRENT_LIMIT_REACHED, DAILY_LIMIT_REACHED, FAIR_USE_LIMIT, REGEN_LIMIT_REACHED) send no header - they clear on a different clock, and resetAt in the body is the field to use where one applies.

Retired codes

These were part of the HMAC request-signing scheme and can no longer be returned as of 2026-07-29. They are listed so a client that still branches on them knows the branch is dead, not that the docs forgot a code.

Was	Code	Why it is gone
401	`MISSING_SIGNATURE_HEADERS`	One header now, so the failure is `MISSING_API_KEY`
401	`INVALID_SIGNATURE` / `TIMESTAMP_SKEW` / `INVALID_TIMESTAMP`	Nothing is signed or timestamped
409	`NONCE_REPLAY`	No nonce, so an identical request is simply replayable

An identical request sent twice now succeeds twice. If you relied on 409 NONCE_REPLAY for idempotency, use clientRunId instead - that is the real idempotency key and always was.

Partial success (207)

Enrich returns HTTP 207 with a success-shaped body when some sections or modules failed while others succeeded. Inspect failures (core sections) and the per-module modules map, then retry the failed parts - the route is idempotent and never regenerates what already completed.

Getting Started

For agents

Concepts

The `upsell` object

Common codes

Retry-After

Retired codes

Partial success (207)

​The upsell object

​Common codes

​Retry-After

​Retired codes

​Partial success (207)

The `upsell` object

Common codes

Retry-After

Retired codes

Partial success (207)