calesthio/OpenMontage · error · RuntimeError

TokenHub API error: code={code}, message={message}

Error message

TokenHub API error: code={code}, message={message}

What it means

RuntimeError from _check_response, the client's mapping of TokenHub top-level error objects. TokenHub returns application errors as {'error': {'message': ..., 'code'|'type': ...}} with a 200-level or 4xx status; this guard runs after every submit and poll call and converts that envelope into a readable exception.

Source

Thrown at tools/graphics/hunyuan_image.py:559

        """Parse JSON response body or raise with HTTP status."""
        try:
            return response.json()
        except ValueError as exc:
            raise RuntimeError(
                f"Non-JSON response from TokenHub API: HTTP {response.status_code}"
            ) from exc

    @staticmethod
    def _check_response(payload: dict[str, Any]) -> None:
        """Check the TokenHub API response for errors.

        TokenHub returns errors at the top level with an ``error`` field.
        """
        error = payload.get("error")
        if error:
            message = error.get("message", "unknown error")
            code = error.get("code", error.get("type", "unknown"))
            raise RuntimeError(
                f"TokenHub API error: code={code}, message={message}"
            )

    # ------------------------------------------------------------------
    # Output helpers
    # ------------------------------------------------------------------

    @staticmethod
    def _resolve_output_paths(base: str, count: int) -> list[Path]:
        """Derive distinct paths for ``count`` images.

        Single image keeps the base path unchanged; multiple images insert an
        index before the extension (foo.png -> foo_1.png, foo_2.png, ...).
        """
        base_path = Path(base)
        if count <= 1:
            return [base_path]
        stem = base_path.stem

View on GitHub (pinned to 95e1c3d0ab)

Solutions

1. Read the code and message in the error text — they are the provider's precise complaint
2. For invalid-parameter errors, diff your request body against the TokenHub API docs for the exact model
3. For quota/billing codes, top up or switch accounts, then retry
4. For auth-type errors, rotate/re-verify TENCENT_TOKENHUB_API_KEY

try:
    data = client._json_or_raise(resp)
    client._check_response(data)
except RuntimeError as e:
    if "TokenHub API error" in str(e):
        # code+message identify the provider complaint; fix input, quota, or key accordingly

When it happens

Trigger: Invalid model name in the request body; malformed or missing required parameters caught by the API; insufficient quota/balance; authentication/permission errors expressed in-body rather than as HTTP status codes.

Common situations: Typo'd model identifier; free-tier quota exhausted; submitting before a required field (e.g. size/callback config) is provided; key valid for a different TokenHub product line.

Related errors

• TokenHub task {task_id} failed: {error_msg}
• Image not found: {path}
• Image too large ({len(raw)} bytes). Max ~6MB raw (8MB base64
• Image too large ({len(raw)} bytes). Max ~6MB raw.
• TokenHub submit returned no task id: {data}

AI-assisted analysis of calesthio/OpenMontage@95e1c3d0ab (2026-08-15). Data as JSON: /api/errors/2815a60ada234b64. Report an issue: GitHub.