Error Handling

All requests return error and error_info fields when an argument is missing or incorrect, or when a problem occurs during processing.

warning

Most API errors return HTTP 200 with error details in the response body. The exceptions are:

http_unauthorized - HTTP 401
http_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 string

Programmatic error identifier. Use this for error handling in your code. Examples: image_no_content, conversion_error.

message string

Human-readable error message describing what went wrong.

detail object (optional)

Additional context (varies by error).

Example response with image_no_content 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 429

Endpoints: All

Your 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

Example response with http_max_requests error
{
  "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

Endpoints: All

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

Endpoints: All

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 401

Endpoints: All

The 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

Endpoints: v3/text, v3/latex, v3/strokes

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 401

Endpoints: All

Your Mathpix account has been disabled by an administrator.
Contact support@mathpix.com to resolve.

expired_license HTTP 401

Endpoints: All

Your 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

Endpoints: All

The request body is not valid JSON.

sys_request_too_large

Endpoints: All

The request body exceeds the maximum allowed size:

Image endpoints - 5 MB
Strokes - 512 KB

See Limits & Quotas for all size limits.

image_missing

Endpoints: v3/text, v3/latex, v3/batch

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

Endpoints: v3/text, v3/latex, v3/pdf

A multipart form-data request was sent but no file was attached.
Ensure the file field is populated in your multipart upload.

strokes_missing

Endpoints: v3/strokes

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

Endpoints: v3/strokes

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

Endpoints: All

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

Endpoints: v3/text, v3/latex

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

Endpoints: All

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

Endpoints: All

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_bad_page_range

Endpoints: v3/pdf, files/v1

A page_ranges entry is not a valid range, or falls outside the document.
Page numbers start at 1, a range must not run backwards, and a negative index counts from the end (-1 is the last page). v3/pdf answers an unparseable entry on the request itself; on files/v1 it fails the document instead. An entry that falls outside the document is only caught once the page count is known, so on both endpoints that fails the document.

Detail field	Description
`range`	The single entry that could not be parsed
`ranges`	The entries that fall outside the document

opts_object_required

Endpoints: All

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

Endpoints: v3/text, v3/latex

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

Endpoints: v3/text, v3/latex

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

Endpoints: v3/latex

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

Endpoints: v3/text, v3/latex

An object parameter is missing one or more required properties.

Detail field	Description
`parameter`	The object parameter name
`properties`	The properties that were provided
`required`	All required properties

Example

A Region object requires the properties top_left_x, top_left_y, width, and height.

opts_property_invalid

Endpoints: v3/text, v3/latex

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

Endpoints: v3/text, v3/latex

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

Endpoints: v3/latex

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

Endpoints: v3/batch

The ocr_behavior parameter only accepts the following values:

"latex"
"text"

Any other value is rejected.

opts_unknown_alphabets_allowed

Endpoints: v3/text, v3/latex, v3/batch, v3/pdf

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

Endpoints: v3/text

The DataOptions object contains a key that is not a recognized data option.
Remove unrecognized keys from the object.

opts_bad_data_options

Endpoints: v3/text

The DataOptions parameter must be an object, but received a different type (e.g. a string or array).

opts_bad_callback

Endpoints: v3/text, v3/latex, v3/batch

The Callback configuration is invalid. Common causes:

post is not a valid URL string
reply is not an object
reply contains the reserved key batch_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

Endpoints: v3/pdf

More than one section numbering flag is set to true. Only one of the following can be enabled per request:

auto_number_sections
remove_section_numbering
preserve_section_numbering

opts_unknown_timespan

Endpoints: v3/ocr-usage

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

Endpoints: v3/text, v3/latex, v3/batch

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

Endpoints: v3/text, v3/latex, v3/batch, v3/pdf

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

Endpoints: v3/text, v3/latex, v3/batch

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_unsupported_content

Endpoints: v3/latex

The image consists only of content the engine doesn't transcribe - geometry figures or diagrams with no recognizable text or math. Returned as the top-level error_info.id.

image_not_supported

Endpoints: v3/text, v3/latex, v3/batch

The image content type is not supported by the OCR engine.
See Supported Formats for accepted image types.

image_max_size

Endpoints: v3/text, v3/latex, v3/batch

The image dimensions or file size exceed the processing limit.
Resize or compress the image and retry.

strokes_no_content

Endpoints: v3/strokes

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

Endpoints: v3/text, v3/latex, v3/batch

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

Endpoints: v3/text, v3/latex, v3/batch

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

Endpoints: v3/pdf

The PDF is password-protected or encrypted and cannot be read.
Remove the encryption before uploading, or provide an unprotected copy.

pdf_missing

Endpoints: v3/pdf

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

Endpoints: v3/pdf

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

Endpoints: v3/pdf

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

Endpoints: v3/batch

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.

Files API errors

The Files API (/files/v1/*) uses a different error model from the v3 endpoints above:

Real HTTP status codes. Unlike v3 (which returns HTTP 200 with errors in the body), Files API errors are returned with the corresponding HTTP status (400, 401, 403, 404, 429, 5xx).
error is a machine code. The error field holds a stable, closed-set error code (e.g. data_source_access_denied).
error_info contains id, which duplicates the machine code, and message, the human-readable description.
When contacting support, quote the file_id (or job_id / data_source_id) involved.

Files API error envelope
{
  "error": "data_source_access_denied",
  "error_info": {
    "message": "Mathpix could not assume the IAM role for bucket 'acme-source'.",
    "id": "data_source_access_denied"
  }
}

Closed error-code set

Code	HTTP	Triggered by	Retry?
`bad_request`	400	Validation failure or malformed JSON	No - fix the request
`unauthorized`	401	Invalid or missing `app_key`	No - fix credentials
`forbidden`	403	`app_key` is valid but not authorized to use the Files API	No
`not_found`	404	File, job, or data source doesn't exist, was deleted, or belongs to another group (indistinguishable by design - see note below)	No
`format_not_ready`	404	Requested output format is still converting	Yes - poll / retry after a short delay
`unsupported_format`	415	Output format wasn't requested, or the input type isn't supported	No - fix the request
`rate_limit_exceeded`	429	Per-minute request / concurrency limit hit	Yes - exponential backoff
`quota_exceeded`	429	Monthly page or file quota reached	No - wait for next billing month or raise the limit
`concurrent_limit_exceeded`	429	Reserved for a future per-app concurrent-document limit	Yes - exponential backoff
`job_too_large`	400	More than 200,000 files in a single job	No - split into multiple jobs
`job_finalized`	409	The job was finalized, so it accepts no more files	No - submit to another job
`conflict`	409	A data source already exists for this `(provider, bucket)` or name in your group - the response carries the existing `data_source_id` in `error_info`	No - reuse it, or delete it first
`data_source_not_found`	404	The bucket in the URI has no registered data source	No - register the data source
`data_source_access_denied`	403	The data source exists but Mathpix can't reach the bucket (grant missing, revoked, or misconfigured)	No - fix the grant; run `/test`
`storage_throttled`	503	Upstream storage backend returned backpressure	Yes - exponential backoff
`internal_error`	500	Unexpected server error	Yes - retry; contact support with the `file_id` if it persists

Retry guidance. Retry the codes marked Yes with exponential backoff (e.g. 1s, 2s, 4s, …). The codes marked No are permanent for the request as-sent - retrying without changing the request (or fixing the underlying grant/quota) will fail again identically.

Anti-enumeration. Accessing a file, job, or data source by an id that belongs to another group returns the same 404 not_found as an id that never existed - identical status, code, and message. This is deliberate: it prevents probing for the existence of other tenants' resources. forbidden (403) is reserved for authorization failures that don't depend on a specific resource (e.g. the app_key isn't authorized to use the Files API).

Asynchronous (result-time) errors

Submissions to POST /files/v1/uri and POST /files/v1/jobs are accepted immediately (200 with a file_id); the source is then fetched and processed off the request thread. A failure during that stage surfaces on GET /files/v1/{file_id} as status: "error" with the same error code + error_info object as request errors (not on the original submit call):

`error` code	Surfaced when
`data_source_not_found`	The `source_uri` bucket has no registered data source for your group.
`data_source_access_denied`	The source returned `401`/`403` - the grant is missing, revoked, or misconfigured.
`not_found`	The source object doesn't exist (`404`) or the URI couldn't be parsed.
`source_unavailable`	The source was unreachable - `5xx`/`408`/`429`, timeout, throttle, or DNS/socket failure (transient; safe to resubmit).
`content_too_large`	The source exceeds the maximum file size (15 GB).
`internal_error`	Unclassified processing failure - resubmit; contact support with the `file_id` if it persists.

ErrorInfo object​

Error categories​

Retryable errors​

Authentication errors​

Request validation errors​

Example​

Example​

Example​

Processing errors​

Files API errors​

Closed error-code set​

Asynchronous (result-time) errors​

ErrorInfo object

Error categories

Retryable errors

Authentication errors

Request validation errors

Example

Example

Example

Processing errors

Files API errors

Closed error-code set

Asynchronous (result-time) errors