PaddlePaddle/PaddleOCR · error · ResponseFormatError

Response body must be a JSON object.

Error message

Response body must be a JSON object.

What it means

Raised as ResponseFormatError by unwrap_api_response() when the parsed response body is not a JSON object (dict). The client expects an envelope object with 'code'/'data'; receiving a list, string, number, or null means the response is not the expected API shape.

Source

Thrown at paddleocr/_api_client/_core.py:164

def raise_for_status(status_code: int, msg: str) -> None:
    if 200 <= status_code < 300:
        return
    if status_code in (401, 403):
        raise AuthError(f"Authentication failed: {msg}")
    if status_code == 400:
        raise InvalidRequestError(f"Bad request: {msg}")
    if status_code == 429:
        raise RateLimitError(f"Rate limit exceeded: {msg}")
    if status_code in (503, 504):
        raise ServiceUnavailableError(status_code, f"Service unavailable: {msg}")
    raise APIError(status_code, msg)


def unwrap_api_response(payload: dict, status_code: int) -> dict:
    if not isinstance(payload, dict):
        raise ResponseFormatError("Response body must be a JSON object.")
    code = payload.get("code", 0)
    if code not in (0, None):
        raise APIError(status_code, extract_api_message_from_payload(payload) or "")
    data = payload.get("data")
    if not isinstance(data, dict):
        raise ResponseFormatError("Response JSON must contain object field 'data'.")
    return data


def extract_job_id(data: dict) -> str:
    job_id = data.get("jobId")
    if not isinstance(job_id, str) or not job_id:
        raise ResponseFormatError(
            "Response data must contain non-empty string 'jobId'."
        )
    return job_id

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Log the raw response text and content-type to identify what was actually returned.
2. Confirm the base URL points at the real API endpoint, not a docs page or proxy error.
3. Update the paddleocr package to match the service schema version.
4. Fix mocks to return the documented {code, data} envelope.

from paddleocr._api_client.errors import ResponseFormatError
try:
    data = await client._http.get_job_status(job_id)
except ResponseFormatError as e:
    log.error("non-object JSON body: %s", e)
    raise

When it happens

Trigger: Any API call whose body parses to non-dict JSON: an array response, a bare string, or a proxy returning a JSON scalar. Also triggered by double-encoded or wrongly-decoded bodies.

Common situations: API version drift changing the envelope, gateways rewriting responses, or test mocks returning list payloads instead of the {code, data} envelope.

Related errors

• Token is required. Set PADDLEOCR_ACCESS_TOKEN or pass token
• Destination parent must be a directory: ${parent}
• Unknown or missing job state: {state}
• 'extractProgress' must be an object.
• Model ${model} is not a document parsing model.

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