PaddlePaddle/PaddleOCR · error · ResponseFormatError

Response body is not valid JSON: {e}

Error message

Response body is not valid JSON: {e}

What it means

ResponseFormatError from _response_data in the async API client: after an HTTP 2xx, the body must parse as JSON (await resp.json()); any parse failure raises with the underlying exception chained. The client assumes successful responses are JSON API envelopes and unwraps them via unwrap_api_response.

Source

Thrown at paddleocr/_api_client/_async_http.py:187

            return
        try:
            body = await resp.json()
            msg = (
                extract_api_message_from_payload(body)
                if isinstance(body, dict)
                else None
            )
            if not msg:
                msg = await resp.text()
        except Exception:
            msg = await resp.text()
        raise_for_status(resp.status, msg)

    async def _response_data(self, resp) -> Dict[str, Any]:
        try:
            payload = await resp.json()
        except Exception as e:
            raise ResponseFormatError(f"Response body is not valid JSON: {e}") from e
        return unwrap_api_response(payload, resp.status)

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Check the base_url/host configuration points at the actual API endpoint, not a frontend.
2. Reproduce with curl and inspect the raw body and Content-Type of the failing response.
3. Retry once — transient gateway HTML pages are common.
4. Report/upgrade if the service legitimately returns a non-JSON success body in a newer version.

import aiohttp, asyncio

async def endpoint_returns_json(base_url: str) -> bool:
    try:
        async with aiohttp.ClientSession() as s:
            async with s.get(base_url) as r:
                ct = r.headers.get("Content-Type", "")
                return "json" in ct
    except aiohttp.ClientError:
        return False

from paddleocr._api_client.errors import ResponseFormatError

try:
    result = await client.parse_document(...)
except ResponseFormatError as e:
    # 2xx with non-JSON body: usually wrong host or gateway page; do NOT retry blindly
    log.error("endpoint returned non-JSON success body: %s", e)
    raise

When it happens

Trigger: Server returns 200 with HTML (login page, maintenance page), plain-text acknowledgment, or an empty body; a proxy or gateway rewriting the response; wrong content-type from a misrouted endpoint.

Common situations: API base URL pointing at a web UI instead of the API host; captive portals in CI networks; partial responses from interrupted connections.

Related errors

• {file_path}
• Malformed JSONL result payload: {e}
• Timed out after {elapsed:.1f}s waiting for job {job_id}
• Expected a JSON response body.
• Token is required. Set PADDLEOCR_ACCESS_TOKEN or pass token

AI-assisted analysis of PaddlePaddle/PaddleOCR@2661c7c0ef (2026-08-14). Data as JSON: /api/errors/01e65a73cf6aee4f. Report an issue: GitHub.