Docs / Reference / Errors

Errors

Error envelopes and status codes across the API, the OpenAI-compatible endpoint, MaxiMind Code, Canvas and the workspace tools.

Envelopes

MaxiMind uses three error shapes depending on the surface.

Native API (/api/ai/*, /jobs*, /v1/transcript and the other media routes, /api/nas/*, /api/canvas/*, /admin/*): a JSON object with detail.

{"detail": "Invalid or missing API key"}

OpenAI-compatible chat (/v1/chat/completions, /v1/models, /api/code/v1/*): OpenAI-shaped error objects with 4xx or 503 status codes. After a stream has started the status cannot change: the failure arrives as an SSE error object followed by [DONE], without a successful stop chunk.

Job-based endpoints report failures inside the job record instead of as HTTP errors: status: "failed" with error on generate and transcription jobs, status: "error" on agent jobs, status: "denied" on worker jobs whose output contained secret-shaped values.

Status codes

Status Where Meaning
400 Native API Bad input: unknown type on /jobs, empty text on TTS, empty prompt on /api/ai/image, URL that cannot be read or downloaded, not a channel or playlist.
400 OpenAI chat Unknown model id, malformed messages, request over the character limit.
400 Canvas Malformed, expired or replayed device flow.
401 All Missing or invalid API key; no session. Code: signed out, revoked or expired device credential. Canvas: invalid session or no browser login.
403 All Account pending ("awaiting admin approval"), suspended or deleted; non-admin deleting another user's NAS file; custom key calling /admin/*; key without the needed capability. Code: MaxiMind Code not enabled. Canvas: disallowed account, Origin or CSRF.
404 Native API No transcript in native mode; job unknown, expired after 1 h or owned by another key; unknown NAS token; TTS or NAS file not found or invalid name.
409 Worker Requested profile is advertised available: false (browser_qa, workspace, notebook, fanout).
413 Native API NAS upload over 5 GB. Canvas: body too large. Generate/agent bodies over 512 KiB / 256 KiB are rejected while the body is still being read.
415 Media Scrape target is not html, xml or text.
422 Media, transcription Invalid url, mode or non-http(s) scrape URL; silent or empty audio detected by the Whisper guard.
426 Code Unsupported X-MaxiMind-Code-Protocol; run maximind update.
429 Model text, Code, Canvas Admission saturated (8 global / 2 per owner; Code: two active requests per account) or a rate limit. Honor Retry-After (5 s on the text surfaces).
500 TTS tts failed: <reason>.
502 Media, NAS Scrape fetch failure; NAS write failure.
503 Images Image generation withheld: Image generation is temporarily unavailable: no host-confined subscription image runtime has passed the safety boundary.
503 OpenAI chat, Code No engine could answer (capacity exhausted or accounts signed out). Body carries sanitized account states.
503 NAS, Canvas NAS not configured; database unavailable.
504 Media Channel or playlist listing exceeded the 120 s yt-dlp timeout.
524 Public edge Request exceeded the edge's 100 s timeout. Use job mode or streaming.

Upstream HTTP errors on /v1/web/scrape are passed through with their own status.

Message strings you will see

Text Surface Cause
Invalid or missing API key 401 native Key missing, wrong or revoked.
awaiting admin approval 403 native Account still pending.
no such job (or it expired after 1h) 404 /jobs/{id} Expired or unknown transcription job.
unknown type: … 400 /jobs Bad output mode.
text is required 400 /api/ai/tts Empty text.
tts failed: … 500 /api/ai/tts Engine error or timeout.
File too large 413 /api/nas/upload Over 5 GB.
Failed to download: … 400 /transcribe-url Media URL not downloadable.
No transcript available… mode='native' was requested. 404 /v1/transcript No platform captions.
this MaxiMind Code version is no longer supported; run maximind update 426 Code Protocol bump.
MaxiMind Code is not enabled for this account 403 Code Ask the owner to enable you at /admin/code.
already has the maximum active requests 429 Code Two active requests per account stayed busy for three minutes.
no subscription could answer 503 Code, failed jobs Shared model capacity used up, or engines signed out.
project boundary refused … Code, local File outside the project, a secret, or a command touching credentials.

Handling advice

  • Treat a slow response as "queued", not failed. Poll job_id endpoints every 1 to 3 s.
  • On 429, wait Retry-After and retry; the prompt was not retained and no quota was spent.
  • On subscription_only failure or 503, your app decides: use your own paid key and log it, or tell the user. MaxiMind never falls back to a paid API on these surfaces.
  • On a streamed SSE error, discard the partial output; there is no stop chunk.
  • Check attachment receipts (status, why, truncated) before treating a document review as complete; a skipped file does not fail the request.
  • Never infer entitlement from a browser page loading or from cached profile data; treat any non-success session response as unauthenticated.