PaddlePaddle/PaddleOCR · error · ResponseFormatError

Response JSON must contain object field 'data'.

Error message

Response JSON must contain object field 'data'.

What it means

Error "Response JSON must contain object field 'data'." thrown in PaddlePaddle/PaddleOCR.

Source

Thrown at paddleocr/_api_client/_core.py:170

        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


def validate_result_json_url(data: dict) -> str:
    result_url = data.get("resultUrl")
    if not isinstance(result_url, dict):
        raise ResponseFormatError("Done job response must contain object 'resultUrl'.")
    json_url = result_url.get("jsonUrl")
    if not isinstance(json_url, str) or not json_url:

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Verify the PaddleOCR API server returned a payload whose top-level 'data' field is a JSON object.
2. Check that you are calling the correct API endpoint and API version; an unexpected response shape usually indicates an endpoint or proxy mismatch.
3. Capture the raw response body (enable debug logging) and confirm it is not an HTML error page from a proxy or gateway.

Example fix

data = resp.json()
if not isinstance(data.get("data"), dict):
    # inspect data to see what the server actually returned
    print(data)

When it happens

Trigger: Raised by unwrap_api_response() when the HTTP response was valid JSON but the 'data' field is missing or is not an object (dict).

Common situations: The official API returned a JSON object whose 'data' field is missing or not an object. This happens with unexpected server responses or proxy-modified payloads. Log the raw response and verify the API endpoint and request parameters.

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