Error Handling and Debugging
The Mathpix Python SDK raises informative errors to help you quickly identify problems with authentication, file inputs, or API usage.
Common Error Types
- AuthenticationError:
Raised when your credentials are missing or invalid.
Make sure yourapp_id
andapp_key
are correctly configured in environment variables or passed to the client.
- ValidationError:
Raised when input parameters are missing, conflicting, or improperly formatted.
For example, callingimage_new()
without eitherfile_path
orurl
.
- FilesystemError:
Triggered if there’s an issue accessing the file system, such as writing to a nonexistent folder.
- ConversionIncompleteError:
Raised when you attempt to retrieve output before the conversion is fully finished.
- MathpixClientError:
A general error class for unexpected issues with the SDK or network.
Debugging Tips
- Enable logging in your app to track request/response activity.
- Check all error messages for helpful context and validation clues.
- Ensure file paths and URLs are valid and accessible.
- Double-check that you’re using the correct SDK method for the content you’re processing.
- Review rate limits in your Mathpix Console if requests are being throttled.
Example Error Handling
from mpxpy.mathpix_client import MathpixClient
from mpxpy.errors import MathpixClientError, ConversionIncompleteError
client = MathpixClient(app_id="your-app-id", app_key="your-app-key")
try:
pdf = client.pdf_new(file_path="example.pdf", convert_to_docx=True)
pdf.wait_until_complete()
result_path = pdf.to_docx_file("output/example.docx")
except ConversionIncompleteError:
print("Conversion is not yet complete. Try again later.")
except MathpixClientError as e:
print(f"Mathpix error: {e}")
except Exception as e:
print(f"Unexpected error: {e}")
Catch specific exceptions like
AuthenticationError
or ValidationError
if you need to handle different failure types differently.