Skip to main content

​
Error Codes

All API errors return a JSON response with a detail field: 
{
  "detail": "Human-readable error message"
}

​
Status codes

CodeMeaningCommon causes
400Bad RequestEmpty message, unsupported file type, invalid parameters
401UnauthorizedMissing or invalid API key, expired token
403ForbiddenAccessing a resource you don’t own
404Not FoundJob, session, template, or attachment doesn’t exist
422Validation ErrorRequest body doesn’t match expected schema
429Too Many RequestsMonthly operation limit reached
500Internal Server ErrorUnexpected server error
504Gateway TimeoutAI processing exceeded 10 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)

{"detail": "Request timed out. The AI agent took longer than 10 minutes to process your request. Please try again with a simpler request or contact support."}
Fix: Simplify your request, or break a complex task into smaller steps. Use the async endpoint (/v1/chat/async) for long operations.

​
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.