Troubleshooting

Errors Reference

A comprehensive guide to handling API errors gracefully. We use standard HTTP codes enhanced with detailed JSON context.

Standard Error Format

All error responses return a standardized JSON object. The detail field contains structured information to help you debug or display user-friendly messages.

error-structure.json

{
  "detail": {
    "error_code": "INVALID_FILE_TYPE",
    "message": "File type not supported. Please upload a PDF or DOCX file.",
    "suggestion": "Convert your file to PDF and try again.",
    "severity": "medium",
    "technical_details": "MIME type detected: application/octet-stream"
  }
}

Errors Reference

Validation Errors

100-199

VALIDATION_ERROR

General validation failure.

INVALID_INPUT

The provided input format is incorrect.

MISSING_FIELD

A required field is missing from the payload.

Authentication Errors

200-299

AUTH_ERROR

Authentication failed.

INVALID_API_KEY

The API key provided is invalid or disabled.

API_KEY_EXPIRED

The API key has expired.

INSUFFICIENT_PERMISSIONS

The API key does not have permission to access that resource.

File Upload Errors

300-399

INVALID_FILE_TYPE

Only PDF and DOCX files are supported.

FILE_TOO_LARGE

File exceeds the maximum size limit (5MB).

FILE_CORRUPTED

The file could not be read or is corrupted.

PDF_QUALITY_ISSUE

The PDF contains scanned images or unreadable text.

Rate Limiting

400-499

RATE_LIMIT_EXCEEDED

Too many requests in a short period.

QUOTA_EXCEEDED

Monthly API quota has been reached.

Server Errors

500-799

PARSING_FAILED

The parsing engine failed to process the document.

AI_PROCESSING_FAILED

The AI model encountered an error analyzing the content.

INTERNAL_ERROR

An unexpected internal server error occurred.

SERVICE_UNAVAILABLE

The service is temporarily unavailable.

Need help debugging?

If you encounter a INTERNAL_ERROR consistently, please contact support with the request ID and timestamp. Note that AI_PROCESSING_FAILED may occur if the input content is too ambiguous or violates safety policies.