Recover from a failed request

Error responses contain code and message. This example shows a missing-document error:

{"code":"missing_input","message":"input is required: attach the document as the 'input' file field."}

Correct the request

Code or response	Action
`missing_input`, `invalid_input`	Supply one supported document source and check the request encoding.
`malformed_schema_json`, `invalid_schema`	Correct JSON syntax and schema constraints.
`schema_too_large`, `file_too_large`	Reduce the input to the documented limit.
`unsupported_file_type`	Use a supported extension and actual file format.
`invalid_output_format`, `output_option_unavailable`	Use a supported output representation and compatible include options.
`unauthorized` / HTTP 401	Supply a valid API key for the target environment.
`forbidden` / HTTP 403	Confirm that the key is authorized for the target environment and resource. If access is still denied with an authorized key, contact support. Do not retry the unchanged request.
`authorization_unavailable` / HTTP 503	Transform could not reach its authorization service. Retry after a delay. If failures continue, contact support with the operation, HTTP status, and public error code.
`not_found` / HTTP 404	Check the ID, credential, and expiry; re-upload if needed.
`parse_not_complete`	Wait for a successful Parse before extracting; inspect failed jobs.
`parse_expired`	Parse the original document again.
`input_url_expired` / HTTP 502	The input URL expired before the worker fetched the document. Retry the original request.
`result_expired` / HTTP 410	The job metadata remains available, but its stored result is no longer available. Re-run the original request.
`quota_exceeded`	Check the response message and your account’s available quota before retrying.
`rate_limited`	The API reference lists this reserved code in `ErrorCode`, but Transform does not currently return this code or provide a `Retry-After` header for it. If you receive it, do not retry automatically; contact support with the operation, HTTP status, and public error code.
`profile_unavailable` / HTTP 502	Parse and direct Extract can return this code. Omit the optional profile or use a profile listed in the Parse reference.
`profile_temporarily_unavailable` / HTTP 503	If the response includes `Retry-After`, wait for the number of seconds specified by that header, then retry the request. If the header is missing, contact support with the operation, HTTP status, and public error code.
`could_not_parse`, `parse_job_failed`	Read the returned message. If the job exceeded the processing time limit, split the document into smaller documents before retrying. Otherwise, verify that the file opens, matches a supported file type, is within the size limit, and has readable text or scanned pages. Correct the file or request before retrying.
`job_not_terminal`	Wait for a terminal status before deleting a job.
`method_not_allowed`	Check the HTTP method in the endpoint reference.
`internal_error` / HTTP 500	If the message names a finished job, follow result retrieval recovery. Upload can also return this response without creating a job. For an upload failure, check the file and request before retrying. If failures continue, contact support with the operation, HTTP status, and public error code.
HTTP 502	Parse and job operations can return this response. If you have a job ID from the request, check that job before resubmitting. Otherwise, retry after checking the request. If failures continue, contact support with the operation, HTTP status, public error code, and any job ID.

Coverage of HTTP statuses and error codes varies by endpoint. The API reference defines each operation’s responses. The Extract reference does not yet list the HTTP 502 profile_unavailable response for direct document extraction. Follow the profile_unavailable guidance in the table if you receive this response.

Retrieve a finished job’s result

An HTTP 500 internal_error can mean that a job finished, but the service could not prepare its result. The job and its stored output remain intact. Do not submit the document again to recover the result. Read the response message to choose the next action:

If the message mentions	Action
Local storage capacity is unavailable	Retrieve the existing job with `GET /api/v2/jobs/{jobId}` after capacity is available. If the failure continues, contact support with the job ID.
The result exceeds the service’s configured retrieval capacity	Contact support with the job ID. Repeating the GET request cannot resolve this limit.

Check a response that looks successful

Before using an HTTP 200 response, check status, warnings, and the expected content field: markdown, elements, or extracted_data. If the expected field is empty or unusable, keep the response and job ID, compare the output with the source document, and follow the support request guidance if the problem continues. An empty result is not confirmation that the document was processed correctly.

If an SSE stream disconnects

A dropped server-sent-events connection leaves the job outcome unknown. Use the same job ID or retrieval path to request the current status and result. If the job is still queued or processing, continue following it through request progress. Do not resubmit until you know the original job has reached a final status.

Report a persistent problem

Provide the operation, HTTP status, public error code, and job ID when you open a support request. Do not send your API key or confidential document contents.

Integrate

API Reference

API endpoints

Recover from a failed request

Correct the request

Retrieve a finished job’s result

Check a response that looks successful

If an SSE stream disconnects

Report a persistent problem

​Correct the request

​Retrieve a finished job’s result

​Check a response that looks successful

​If an SSE stream disconnects

​Report a persistent problem

Correct the request

Retrieve a finished job’s result

Check a response that looks successful

If an SSE stream disconnects

Report a persistent problem