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.

Error response format

{
  "error": "Human-readable error message",
  "error_info": {
    "id": "error_id_string",
    "message": "Human-readable error message",
    "detail_field": "additional context (varies by error)"
  }
}

id string

Programmatic error identifier

message string

Human-readable error message

detail object (optional)

Additional context (varies by error)

Error categories

Retryable errors

Transient errors that may succeed on retry with exponential backoff.

Id	Description	Detail fields	HTTP Status	Endpoints
http_max_requests	Monthly quota or per-minute rate limit exceeded	limit_name, limit_value, count	429	All
sys_exception	Internal server error	—	200	All
connection_closed	Client disconnected before response was sent	—	200	All

Example http_max_requests response:

{
  "error": "Too many requests",
  "error_info": {
    "id": "http_max_requests",
    "message": "Too many requests",
    "limit_name": "page_monthly_limit",
    "limit_value": 5000,
    "count": 5001
  }
}

Authentication errors

Returned when credentials are invalid or the account is not active.

Id	Description	HTTP Status	Endpoints
http_unauthorized	Invalid or missing app_id/app_key headers	401	All
unauthorized_token_request	Invalid app_token, or attempted batch/async with app token	200	v3/text, v3/latex, v3/strokes
account_disabled	Account has been disabled	401	All
expired_license	On-premises license has expired	401	All

Request validation errors

Returned when the request body or parameters are malformed or out of range.

Id	Description	Detail fields	Endpoints
json_syntax	JSON body could not be parsed		All
sys_request_too_large	Request body exceeds size limit (5 MB for images, 512 KB for strokes). See Limits & Quotas		All
image_missing	No src or url field in request body		v3/text, v3/latex, v3/batch
file_missing	No file in multipart form-data request		v3/text, v3/latex, v3/pdf
strokes_missing	No strokes field in request body		v3/strokes
strokes_syntax_error	Strokes JSON is malformed or missing x/y arrays		v3/strokes
opts_value_out_of_range	Numeric parameter outside valid range	name, value	All
opts_number_required	Parameter must be a number (e.g. beam_size required when n_best is set)	name, value	v3/text, v3/latex
opts_boolean_required	Parameter must be a boolean. Accepted values: true, false, 1, 0, "true", "false" (case-insensitive). Other values (e.g., "yes", -1) are rejected	name, value	All
opts_string_required	Parameter must be a string	name, value	All
opts_object_required	Parameter must be an object	name, value	All
opts_expected_array	Parameter must be an array	name, value	v3/text, v3/latex
opts_string_array_required	Parameter must be a string array	name, value	v3/text, v3/latex
opts_array_length_mismatch	Array has wrong length (e.g. math_delims must be [begin, end])	name, value	v3/latex
opts_property_required	Object missing required properties (e.g. region needs top_left_x, top_left_y, width, height)	name, value	v3/text, v3/latex
opts_property_invalid	Object contains unknown properties	name, value	v3/text, v3/latex
opts_unknown_format	Unknown value in formats array	formats	v3/text, v3/latex
opts_unknown_ocr	Unknown value in ocr array	ocr	v3/latex
opts_unknown_ocr_behavior	ocr_behavior must be "latex" or "text"		v3/batch
opts_unknown_alphabets_allowed	Unknown key in alphabets_allowed object. See supported languages		v3/text, v3/latex, v3/batch, v3/pdf
opts_unknown_data_option	Unknown key in data_options object		v3/text
opts_bad_data_options	data_options must be an object		v3/text
opts_bad_callback	Invalid callback configuration (e.g. post not a string, reply not an object, or reply contains batch_id)	post?, reply?, batch_id?	v3/text, v3/latex, v3/batch
opts_section_numbering	Multiple section numbering flags set. Only one of auto_number_sections, remove_section_numbering, or preserve_section_numbering can be set per request		v3/pdf
opts_unknown_timespan	Unknown timespan value in usage query		v3/ocr-usage

Processing errors

Returned when the input is valid but the content could not be processed.

Id	Description	Endpoints
image_download_error	Could not download image from URL (timeout after 15s, exceeds 10 MB, or URL unreachable)	v3/text, v3/latex, v3/batch
image_decode_error	Image data could not be decoded (corrupt or unsupported format)	v3/text, v3/latex, v3/batch, v3/pdf
image_no_content	No recognizable content found in image	v3/text, v3/latex, v3/batch
image_not_supported	Image content type not supported by the OCR engine	v3/text, v3/latex, v3/batch
image_max_size	Image is too large to process	v3/text, v3/latex, v3/batch
strokes_no_content	No recognizable content found in strokes	v3/strokes
math_confidence	Recognition confidence below threshold	v3/text, v3/latex, v3/batch
math_syntax	Could not parse recognized content as valid math	v3/text, v3/latex, v3/batch
pdf_encrypted	PDF is encrypted and cannot be read	v3/pdf
pdf_missing	No url field in PDF request body	v3/pdf
pdf_unknown_id	PDF ID not found (expired or invalid)	v3/pdf
pdf_page_limit_exceeded	PDF exceeds maximum page limit	v3/pdf
batch_unknown_id	Batch ID not found	v3/batch