PaddlePaddle/PaddleOCR · critical · AuthError

Authentication failed: {msg}

Error message

Authentication failed: {msg}

What it means

Raised as AuthError by raise_for_status() when the HTTP response status is 401 or 403. The message embeds the API-provided text. It means the API key is missing, invalid, expired, or lacks permission for the requested resource.

Source

Thrown at paddleocr/_api_client/_core.py:152

            total_pages=ep.get("totalPages", 0),
            extracted_pages=ep.get("extractedPages", 0),
            start_time=ep.get("startTime"),
            end_time=ep.get("endTime"),
        )
    return JobStatus(
        job_id=job_id,
        state=state,
        progress=progress,
        result=data.get("resultUrl"),
        error_msg=data.get("errorMsg"),
    )


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'.")

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Verify the API key is set and was copied exactly (no surrounding whitespace).
2. Confirm the key is still active and has access to the model/endpoint being called.
3. Check you are pointing at the correct environment/base URL for that key.
4. Regenerate the key if compromised or revoked, then update your environment/config.

Example fix

# before
client = PaddleOCRClient(apikey=os.environ.get("PADDLE_API_KEY"))  # may be None/empty

# after
key = os.environ["PADDLE_API_KEY"].strip()
assert key, "PADDLE_API_KEY must be set"
client = PaddleOCRClient(apikey=key)

key = (os.environ.get("PADDLE_API_KEY") or "").strip()
if not key:
    raise RuntimeError("PADDLE_API_KEY is not set")
client = PaddleOCRClient(apikey=key)

from paddleocr._api_client.errors import AuthError
try:
    result = await client.ocr(file_path=p)
except AuthError:
    alert("credentials rejected; halting batch")
    raise  # do not retry with the same key

When it happens

Trigger: Any HTTP call (job creation, status, result fetch, file upload) returning 401/403: bad apikey, key from a different environment, revoked token, or accessing another account's resource id.

Common situations: API key typo or copied with whitespace/newline, expired AI Studio token, key valid in dev but not prod, or environment variable not set so an empty key is sent.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Expected a JSON response body.
• PaddleOCR official API request failed.
• Response body is missing data.
• Request timed out after ${timeoutMs}ms
• Authentication failed: ${text}

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