Skip to main content
When something goes wrong, Reducto returns an HTTP status code and error message.

​
Error Response Format

{
  "error": {
    "message": "Failed to download file from url. Please check the document url and try again",
    "type": "file_download_failure",
    "code": 400
  }
}

​
Client Errors (4xx)

These errors indicate a problem with your request.
CodeNameDescriptionSolution
400JSON decoding errorLLM response too large to decodeEnable array_extract: true for large extraction schemas
400Invalid URL formatS3 URL malformedUse format s3://bucket-name/key
400File download failureCannot fetch document from URLVerify URL is accessible and not expired
400Invalid page rangeSpecified pages don’t existPage range is 1-indexed. Check document has requested pages
403Permission errorURL access forbiddenEnsure presigned URL hasn’t expired or credentials are valid
403PDF processing errorCannot write outputInternal error, contact support
404File access errorFile not foundVerify file exists at the specified path/URL
415File conversion errorCannot convert to imagesCheck file is a valid, uncorrupted PDF
415PDF handling errorCannot process PDFFile may be corrupted. Try re-saving with Adobe Acrobat
422Schema validation errorInvalid JSON schemaValidate your schema is proper JSON Schema format
422Table processing errorTable extraction failedRetry, or enable agentic table mode for complex tables
442Document access errorPassword protectedProvide password via settings.document_password
429Rate limit exceededToo many requestsImplement backoff, or switch to async endpoints

​
Server Errors (5xx)

These indicate a problem on Reducto’s side. Most are automatically retried by the SDK.
CodeNameDescriptionRetriable?
500Content extraction errorExtraction failed❌ No
500Citation extraction errorCitation extraction failed❌ No
500PDF metadata errorPDF metadata corrupted❌ No
502LLM service errorLLM provider error✅ Yes
503Service unavailableTemporary overload✅ Yes
503Table processing errorTable service error✅ Yes
504LLM timeout errorLLM provider timed out✅ Yes
504Document conversion timeoutConversion took too long✅ Yes

​
Automatic Retries

The Reducto SDKs automatically retry requests that fail with these status codes: 
408, 409, 429, and all 5xx errors (500+)
Default retry behavior:
  • Max retries: 2
  • Backoff: Exponential with jitter
  • Timeout: 1 hour per request (3600 seconds)
You can customize retry behavior: 
from reducto import Reducto

client = Reducto(
    max_retries=5,
    timeout=120.0  # seconds
)

​
Handling Errors

from reducto import (
    Reducto,
    APIError,
    BadRequestError,
    RateLimitError,
    APIConnectionError
)

client = Reducto()

try:
    result = client.parse.run(input=upload.file_id)
except BadRequestError as e:
    # 400-level errors (your request has a problem)
    print(f"Bad request: {e.message}")
except RateLimitError as e:
    # 429 - too many requests
    print("Rate limited, waiting...")
    time.sleep(60)
except APIConnectionError as e:
    # Network issues
    print(f"Connection failed: {e}")
except APIError as e:
    # Other API errors
    print(f"API error {e.status_code}: {e.message}")

​
Common Issues

Cause: The URL you provided isn’t in a recognized format.Solutions:
  • For S3: Use s3://bucket-name/key format
  • For presigned URLs: Ensure the full URL including query parameters is provided
  • For reducto:// URLs: Use the exact string returned from /upload
Cause: Reducto cannot access the file at the URL you provided.Solutions:
  • Check that presigned URLs haven’t expired
  • Verify the URL is publicly accessible or properly authenticated
  • For S3, ensure the bucket policy allows access from Reducto’s IPs
Cause: You’ve exceeded the request rate limit.Solutions:
  • Implement exponential backoff
  • Switch to async endpoints (/parse_async) which have higher limits
  • Use separate API keys for different applications
  • Contact support for higher limits
Cause: The document took too long to process.Solutions:
  • Use async endpoints for large documents
  • Process fewer pages using page_range
  • Disable agentic modes if not needed
  • Check if the document is unusually complex

Rate Limits

Understanding request limits.

Async Processing

Avoid timeouts with async endpoints.