Error Handling
All requests return error and error_info fields when an argument is missing or incorrect, or when a problem occurs during processing.
Most API errors return HTTP 200 with error details in the response body. The exceptions are:
http_unauthorized— HTTP 401http_max_requests— HTTP 429
The error_info.id field is the reliable error identifier across all endpoints.
ErrorInfo object
The error_info object is present in error responses across all endpoints with the following fields:
id Programmatic error identifier. Use this for error handling in your code. Examples: image_no_content, conversion_error.
message Human-readable error message describing what went wrong.
detail Additional context (varies by error).
{
"error": "Image has no content",
"error_info": {
"id": "image_no_content",
"message": "Image has no content"
}
}
Error categories
Retryable errors
Transient errors that may succeed on retry with exponential backoff.
http_max_requests HTTP 429Your account has exceeded its monthly page or image quota, or you are sending too many requests per minute.
Wait before retrying, or upgrade your plan for higher limits.
| Detail field | Description |
|---|---|
limit_name | Which limit was hit |
limit_value | The limit threshold |
count | Current usage count |
{
"error": "Too many requests",
"error_info": {
"id": "http_max_requests",
"message": "Too many requests",
"limit_name": "page_monthly_limit",
"limit_value": 5000,
"count": 5001
}
}
sys_exception Something went wrong on our servers while processing your request. This is not caused by your input.
Retry the same request after a brief delay — these are typically transient.
connection_closed Your HTTP client closed the connection before the server finished sending the response.
This usually happens when a client-side timeout fires before OCR completes.
Increase your client timeout or use smaller images for faster processing.
Authentication errors
Returned when credentials are invalid or the account is not active.
http_unauthorized HTTP 401The app_id or app_key header is missing, empty, or does not match any active account.
Double-check that both headers are present and correctly spelled. See Authentication.
unauthorized_token_request The app_token is invalid, expired, or was used to call a batch/async endpoint that requires full app_id/app_key credentials.
App tokens are only valid for synchronous image endpoints. See App Tokens.
account_disabled HTTP 401Your Mathpix account has been disabled by an administrator.
Contact support@mathpix.com to resolve.
expired_license HTTP 401Your on-premises license key has expired.
Contact your Mathpix account representative to renew.
Request validation errors
Returned when the request body or parameters are malformed or out of range.
json_syntax The request body is not valid JSON.
sys_request_too_large The request body exceeds the maximum allowed size:
- Image endpoints — 5 MB
- Strokes — 512 KB
See Limits & Quotas for all size limits.
image_missing The request body does not contain a src field (for image URL or base64 data).
Either include src in the JSON body or send the image via multipart form-data.
file_missing A multipart form-data request was sent but no file was attached.
Ensure the file field is populated in your multipart upload.
strokes_missing The request body does not contain a strokes field.
This endpoint requires handwriting stroke data as an array of stroke objects, each with x and y coordinate arrays.
strokes_syntax_error The strokes data could not be parsed.
Each stroke object must contain x and y arrays of equal length representing pen coordinates.
opts_value_out_of_range A numeric parameter was set to a value outside its allowed range.
Refer to the endpoint documentation for valid ranges.
| Detail field | Description |
|---|---|
name | The parameter name |
value | The value that was provided |
opts_number_required A parameter that must be a number received a non-numeric value.
| Detail field | Description |
|---|---|
name | The parameter name |
value | The value that was provided |
Example
beam_size must be an integer when n_best is set.
opts_boolean_required A parameter that must be a boolean received an invalid value. Accepted values (case-insensitive):
| Value | Maps to |
|---|---|
true, 1, "true" | true |
false, 0, "false" | false |
Values like "yes" or -1 are rejected.
| Detail field | Description |
|---|---|
name | The parameter name |
value | The value that was provided |
opts_string_required A parameter that must be a string received a different type (e.g. a number or object).
| Detail field | Description |
|---|---|
name | The parameter name |
value | The value that was provided |
opts_object_required A parameter that must be an object received a different type (e.g. a string or array).
| Detail field | Description |
|---|---|
name | The parameter name |
value | The value that was provided |
opts_expected_array A parameter that must be an array received a different type.
| Detail field | Description |
|---|---|
option | The parameter name |
type | The actual type received |
opts_string_array_required A parameter that must be an array of strings received an array containing non-string values, or a non-array type entirely.
| Detail field | Description |
|---|---|
tags | The invalid value provided |
opts_array_length_mismatch An array parameter has the wrong number of elements.
| Detail field | Description |
|---|---|
option | The parameter name |
length | The expected length |
Example
math_delims must be exactly [begin, end] — a two-element array.
opts_property_required opts_property_invalid An object parameter contains properties that are not recognized.
| Detail field | Description |
|---|---|
parameter | The object parameter name |
properties | The unrecognized properties |
required | The allowed properties |
opts_unknown_format The formats array contains a value that is not a recognized output format.
See Conversion Formats for the list of valid format names.
| Detail field | Description |
|---|---|
formats | The unrecognized format value |
opts_unknown_ocr The ocr array contains a value that is not a recognized OCR engine option.
Check the v3/latex endpoint documentation for valid values.
| Detail field | Description |
|---|---|
ocr | The unrecognized OCR value |
opts_unknown_ocr_behavior The ocr_behavior parameter only accepts the following values:
"latex""text"
Any other value is rejected.
opts_unknown_alphabets_allowed The AlphabetsAllowed object contains a key that is not a recognized alphabet code.
See DetectedAlphabet for valid keys (e.g. en, ru, zh).
opts_unknown_data_option The DataOptions object contains a key that is not a recognized data option.
Remove unrecognized keys from the object.
opts_bad_data_options The DataOptions parameter must be an object, but received a different type (e.g. a string or array).
opts_bad_callback The Callback configuration is invalid. Common causes:
postis not a valid URL stringreplyis not an objectreplycontains the reserved keybatch_id
| Detail field | Description |
|---|---|
post | The invalid post URL |
reply | The invalid reply object |
batch_id | Present if reply contains reserved key |
opts_section_numbering More than one section numbering flag is set to true. Only one of the following can be enabled per request:
auto_number_sectionsremove_section_numberingpreserve_section_numbering
opts_unknown_timespan The timespan query parameter contains an unrecognized value.
Check the v3/ocr-usage endpoint documentation for valid timespan values.
Processing errors
Returned when the input is valid but the content could not be processed.
image_download_error The server could not download the image from the URL you provided. This happens when:
- The URL is unreachable or returns a non-image response
- The download takes longer than 15 seconds
- The remote file exceeds 10 MB
Verify the URL is publicly accessible and returns an image.
image_decode_error The image data could not be decoded. The file may be corrupt, truncated, or in an unsupported format.
See Supported Formats for accepted image types.
image_no_content The image was successfully received but the OCR engine found no recognizable text, math, or diagrams.
This can happen with blank images, images with only decorative elements, or very low-resolution content.
image_not_supported The image content type is not supported by the OCR engine.
See Supported Formats for accepted image types.
image_max_size The image dimensions or file size exceed the processing limit.
Resize or compress the image and retry.
strokes_no_content The stroke data was received but the recognition engine could not identify any text or math from the handwriting.
This can happen when strokes are too short, scattered, or do not form recognizable characters.
math_confidence The OCR engine recognized content but the confidence score is below the minimum threshold.
The image may be too blurry, low-resolution, or contain ambiguous content. Try a higher-quality image.
math_syntax The OCR engine recognized characters but could not assemble them into syntactically valid math.
This can happen with unusual notation or heavily overlapping symbols.
pdf_encrypted The PDF is password-protected or encrypted and cannot be read.
Remove the encryption before uploading, or provide an unprotected copy.
pdf_missing The request body does not contain a url field and no file was uploaded.
Either include a url pointing to the PDF, or upload the file via multipart form-data.
pdf_unknown_id The pdf_id does not match any existing document.
The ID may have expired (results are retained for a limited time), or it may be a typo.
Check that you are using the pdf_id returned by the original POST request.
pdf_page_limit_exceeded The PDF has more pages than your account's per-document limit allows.
Split the document into smaller parts using page_ranges, or contact support to increase your limit.
batch_unknown_id The batch_id does not match any existing batch.
The ID may have expired, or it may be a typo.
Check that you are using the batch_id returned by the original POST request.