Error Codes

All API errors return a JSON response with a detail field:

{
  "detail": "Human-readable error message"
}

Status codes

Code	Meaning	Common causes
400	Bad Request	Empty message, unsupported file type, invalid parameters
401	Unauthorized	Missing or invalid API key, expired token
403	Forbidden	Accessing a resource you don’t own
404	Not Found	Job, session, template, or attachment doesn’t exist; revert target message not in active history; pre-signed upload expired
409	Conflict	Revert blocked because a chat job is currently running on the same session
413	Request Entity Too Large	Request body or export payload above the size cap
422	Validation Error	Request body doesn’t match expected schema; format value outside the allowed enum; revert target message predates the revert feature
429	Too Many Requests	Monthly operation limit reached
500	Internal Server Error	Unexpected server error
504	Gateway Timeout	AI processing exceeded 30 minutes

Common errors and fixes

Authentication errors (401)

{"detail": "Invalid authorization header format. Expected 'Bearer <api_key>'"}

Fix: Use Authorization: Bearer sk_YOUR_KEY (include the Bearer prefix).

{"detail": "Invalid API key"}

Fix: Check that your key is correct and hasn’t been revoked. Generate a new key from Settings > API Keys.

Validation errors (400)

{"detail": "Message cannot be empty. Please provide a text message."}

Fix: Include a non-empty message in your request body.

{"detail": "Legacy .doc files are not supported. Please convert to .docx format and try again."}

Fix: Use a supported format (.pdf, .docx, .txt, .rtf, .md). Convert .doc files to .docx.

Rate limit (429)

{"detail": "Monthly operation limit (500) reached. Upgrade your plan for more operations."}

Fix: Upgrade your plan at Settings > Billing, or wait for your monthly reset. Check the usage object in chat responses to monitor remaining operations.

Timeout (504)

The synchronous /v1/chat and async /v1/chat/async endpoints both apply a 30-minute wall-clock cap. When the cap is reached, the response carries a short summary and a suggestion to split the work across smaller turns:

⏱️ Your request ran past my 30-minute cap and I had to wrap up. For very large
documents, try splitting the task into multiple smaller turns — e.g. one section
at a time. Your prompt is still in your history above; you can revise it and
re-send.

Fix: Use the async endpoint (/v1/chat/async) for long operations — it streams intermediate progress events as the work runs and supports human-in-the-loop approval. Split large requests into smaller turns (one section per turn).

Request too large (413)

The 413 response covers two distinct cases — caller-too-large and document-too-large for the chosen export format — with a structured JSON detail body so clients can react appropriately. Caller payload exceeds the transport limit:

{
  "detail": "Request body too large",
  "error_code": "request_too_large",
  "message_user": "Your request is too large. The current limit is 32 MB.",
  "request_size_mb": 47.2,
  "max_size_mb": 32,
  "suggested_action": "split_request",
  "contact_email": "hello@superdocs.app",
  "support_event_id": "abc1234567890"
}

Fix: For exports, switch to the upload-then-export pattern — see Large documents. For other endpoints, split the work into smaller requests. Export payload exceeds the format-specific cap:

{
  "detail": {
    "error_code": "document_too_large",
    "message_user": "This document is 142.3 MB, which exceeds the 100 MB export limit for the chosen format. Email hello@superdocs.app or use the in-app 'Email me a copy' button — we'll send you the rendered file within 24 hours.",
    "suggested_action": "email_request",
    "contact_email": "hello@superdocs.app",
    "document_size_mb": 142.3,
    "max_size_mb": 100,
    "format": "docx",
    "support_event_id": "abc1234567890"
  }
}

Fix: Call POST /v1/documents/export/email-request instead — the file will be rendered in the background and emailed as a 7-day signed download link. See Email fallback for very large documents.

Field	Description
`error_code`	`request_too_large` (transport layer) or `document_too_large` (export cap).
`message_user`	Human-readable explanation safe to surface in your UI.
`suggested_action`	`split_request` or `email_request`. Use to switch your client between paths.
`request_size_mb` / `document_size_mb`	Observed payload size.
`max_size_mb`	Configured cap for the format / endpoint.
`format`	Export format that triggered the cap (only on `document_too_large`).
`contact_email`	Support contact for follow-up.
`support_event_id`	Opaque correlation ID. Share with `hello@superdocs.app` when reporting an issue.

Validation errors (422)

{"detail": [{"type": "literal_error", "loc": ["body", "format"], "msg": "Input should be 'docx', 'pdf', 'html', 'markdown', 'txt' or 'doc'"}]}

Fix: format is now a strict enum on /v1/documents/export. Use one of "docx", "pdf", "html", "markdown", "txt". The value "doc" is accepted as a legacy alias and will be removed in a future release.

Not found (404)

{"detail": "Job not found"}

Fix: Jobs are cleaned up 1 hour after completion. Check the job ID and timing. Use /v1/jobs to list active jobs.

Revert conflicts (409)

{"detail": "Cannot revert while a chat job is running for this session. Wait for it to complete or cancel it first."}

Fix: Wait for the in-flight job to finish (poll /v1/jobs/{job_id} or watch the SSE stream until you see final), or cancel it via POST /v1/jobs/{job_id}/cancel before retrying revert.

Revert target too old (422)

{"detail": "This message predates the revertability feature and cannot be reverted. Start a new chat to use revert."}

Fix: Per-message revert only works for chats started after the feature shipped. Older sessions remain readable but their messages don’t carry the marker the rewind needs. Start a new session for full revert support.

​Error Codes

​Status codes

​Common errors and fixes

​Authentication errors (401)

​Validation errors (400)

​Rate limit (429)

​Timeout (504)

​Request too large (413)

​Validation errors (422)

​Not found (404)

​Revert conflicts (409)

​Revert target too old (422)