Recover from a failed request

Match Transform error codes to fixes for rejected input, expired results, and access failures. Check existing jobs before retrying a 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 / HTTP 403	The free page allowance is used up. Add a payment method before resubmitting the request. See Transform billing.
insufficient_balance / HTTP 402	The account has no balance left for this job. Review your billing details and contact Unstructured Support for help restoring balance. Resubmit after balance is available. No job was created.
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.

​

Recover from an insufficient balance

HTTP 402 with insufficient_balance rejects a Parse or Extract request before creating a job. Add balance before resubmitting the request.

The response includes these fields in addition to code and message:

• balance_usd: available account balance in US dollars.
• jobs_still_running: number of account jobs still running. Those jobs finish normally.
• job_id: always null, because the rejected request created no job.

The balance error differs from HTTP 403 with quota_exceeded, which reports an exhausted free page allowance. Inspect the error code to choose the recovery action.

​

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.