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, invalid parameters
401	Unauthorized	Missing or invalid API key, expired token
403	Forbidden	Accessing a resource you don’t own; wrong agent-takeover code (the `detail` says how many attempts remain)
404	Not Found	Job, session, template, or attachment doesn’t exist; revert target message not in active history; pre-signed upload expired; expired or unknown agent-takeover link
409	Conflict	Revert blocked because a chat job is currently running on the same session
410	Gone	Agent-takeover link permanently disabled after too many incorrect codes. Terminal: the old link can never work again; the agent must send a fresh handoff link
413	Request Entity Too Large	Request body or export payload above the size cap
415	Unsupported Media Type	Upload file extension not supported, including a legacy `.doc` upload (convert to `.docx`); use `.pdf`, `.docx`, `.txt`, `.rtf`, `.md`, `.html`, `.htm`
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, or an endpoint-specific cooldown. Application 429s are JSON and always carry a `Retry-After` header (seconds); see Rate Limits
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.

Unsupported file type (415)

{"detail": "Unsupported file type: .xyz. Supported types: .pdf, .docx, .txt, .rtf, .md, .html, .htm"}

A legacy binary .doc upload returns the same 415:

{"detail": "Unsupported file type: .doc. Supported types: .pdf, .docx, .txt, .rtf, .md, .html, .htm"}

Fix: Upload one of the supported formats — .pdf, .docx, .txt, .rtf, .md, .html, .htm. Convert legacy .doc files to .docx first. RTF is supported as an upload input only; it is not an export target. Catch 415 (Unsupported Media Type) separately from 400 when handling upload-validation failures.

Rate limit (429)

{"detail": "Your monthly operation quota (500) is exhausted. Upgrade to Pro for uninterrupted pay-as-you-go overage."}

Fix: Upgrade your plan at Settings > Billing, or wait for your monthly reset. Honor the Retry-After header (seconds until the request can succeed) and branch on the 429 status and the X-Usage-Limit / X-Usage-Used / X-Usage-Remaining headers rather than the detail string (the wording may change). Check the usage object in chat responses to monitor remaining operations. A plain-text 429 with no Retry-After is an infrastructure surge response, not an application error; back off with jitter and retry (see Rate Limits).

Timeout (504)

Both the synchronous /v1/chat and the async /v1/chat/async endpoints apply a 30-minute wall-clock cap, but they surface the timeout differently: Synchronous /v1/chat returns an HTTP 504 with a plain detail string:

{"detail": "The AI agent took longer than 30 minutes to process your request. For long edits or multi-step tasks, use chat_async."}

Async /v1/chat/async does not return a 504 on the poll — the job completes and the friendly summary below is persisted as the job’s AI response (read it from the job result):

⏱️ 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 100 MB.",
  "request_size_mb": 142.3,
  "max_size_mb": 100,
  "suggested_action": "split_request",
  "contact_email": "hello@superdocs.app",
  "support_event_id": "abc1234567890"
}

A much smaller ~32 MiB platform limit sits in front of the application. A body over that ceiling is rejected at the gateway with a generic error page (HTML), not this structured JSON body — so don’t try to parse it as JSON. Keep request bodies well under that limit; for large exports, switch to the upload-then-export pattern below.

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.

{"detail": [{"type": "string_pattern_mismatch", "loc": ["body", "session_id"], "msg": "String should match the expected pattern"}]}

Fix: session_id may contain only letters, digits, and the characters _, -, and ., up to a maximum of 256 characters. Drop spaces, slashes, and other punctuation from the id you choose.

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.

Getting Started

Capabilities

Account & Billing

Core Concepts

Guides

MCP Integration

Errors & Limits

Code Examples

Error Codes

Error Codes

Status codes

Common errors and fixes

Authentication errors (401)

Validation errors (400)

Unsupported file type (415)

Rate limit (429)

Timeout (504)

Request too large (413)

Validation errors (422)

Not found (404)

Revert conflicts (409)

Revert target too old (422)

​Error Codes

​Status codes

​Common errors and fixes

​Authentication errors (401)

​Validation errors (400)

​Unsupported file type (415)

​Rate limit (429)

​Timeout (504)

​Request too large (413)

​Validation errors (422)

​Not found (404)

​Revert conflicts (409)

​Revert target too old (422)

Error Codes

Status codes

Common errors and fixes

Authentication errors (401)

Validation errors (400)

Unsupported file type (415)

Rate limit (429)

Timeout (504)

Request too large (413)

Validation errors (422)

Not found (404)

Revert conflicts (409)

Revert target too old (422)