{"record":{"id":"ec1f99fcb0af14e3","repo":"calesthio/OpenMontage","slug":"http-http-status-code-code-message-hint","errorCode":null,"errorMessage":"HTTP {http_status}, code {code}: {message}{hint}","messagePattern":"HTTP (.+?), code (.+?): (.+?)(.+?)","errorType":"http","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"tools/audio/doubao_tts.py","lineNumber":376,"sourceCode":"                return query_data\n            if status == 3:\n                raise RuntimeError(f\"Doubao task failed: {query_data.get('message', 'unknown error')}\")\n        raise TimeoutError(f\"Doubao task did not finish within {timeout_seconds} seconds\")\n\n    @staticmethod\n    def _json_or_raise(response: Any) -> dict[str, Any]:\n        try:\n            return response.json()\n        except ValueError as exc:\n            raise RuntimeError(f\"Non-JSON response from Doubao API: HTTP {response.status_code}\") from exc\n\n    def _raise_for_doubao_error(self, http_status: int, payload: dict[str, Any]) -> None:\n        code = payload.get(\"code\")\n        if http_status < 400 and code == 20000000:\n            return\n        message = payload.get(\"message\", \"unknown error\")\n        hint = self._diagnostic_hint(message)\n        raise RuntimeError(f\"HTTP {http_status}, code {code}: {message}{hint}\")\n\n    @staticmethod\n    def _diagnostic_hint(message: str) -> str:\n        lowered = message.lower()\n        if \"load grant\" in lowered or \"requested grant not found\" in lowered:\n            return \" (check DOUBAO_SPEECH_API_KEY and use the new-console X-Api-Key flow)\"\n        if \"speaker permission denied\" in lowered or \"access denied\" in lowered:\n            return \" (check voice_id/DOUBAO_SPEECH_VOICE_TYPE and voice authorization)\"\n        if \"quota exceeded\" in lowered:\n            return \" (check quota, concurrency, or remaining character package)\"\n        if \"unsupported additions explicit language\" in lowered:\n            return \" (do not pass additions.explicit_language for this endpoint)\"\n        return \"\"\n\n    @staticmethod\n    def _safe_error(exc: Exception) -> str:\n        # Avoid ever echoing request headers or secrets in user-visible errors.\n        return str(exc).replace(os.environ.get(\"DOUBAO_SPEECH_API_KEY\", \"\"), \"[redacted]\")","sourceCodeStart":358,"sourceCodeEnd":394,"githubUrl":"https://github.com/calesthio/OpenMontage/blob/95e1c3d0ab93482159818560f6a8c8e866b9139f/tools/audio/doubao_tts.py#L358-L394","documentation":"Template for the central Doubao error raiser _raise_for_doubao_error. It fires when either HTTP status >= 400 or payload code != 20000000, formatting status, code, message, and a diagnostic hint derived from the message text. Hints map known failure strings to fixes: 'load grant' → X-Api-Key flow, 'speaker permission denied' → voice authorization, 'quota exceeded' → quota/concurrency, 'unsupported additions explicit language' → drop that field.","triggerScenarios":"Any API-level rejection on submit or query: bad/expired DOUBAO_SPEECH_API_KEY, unauthorized voice_id, exhausted quota or concurrency, explicit_language passed to an endpoint that forbids it.","commonSituations":"Old bearer-token key used with the new-console X-Api-Key flow; voice_type cloned in a different account; free character package depleted mid-batch; SDK version mismatch adding unsupported fields.","solutions":["Parse the appended hint — it names the exact fix for the four known message classes","For load-grant errors: re-issue the key from the new Volcengine console and send it via X-Api-Key header","For voice errors: confirm voice_id/DOUBAO_SPEECH_VOICE_TYPE is authorized for this account","For quota errors: top up the character package or reduce concurrency","Otherwise quote code + message to Volcengine support"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    result = doubao_tool.execute(inputs)\nexcept RuntimeError as e:\n    # message already carries a targeted hint; surface it to the user verbatim\n    show_user_error(str(e))","preventionTips":["Issue keys via the new-console X-Api-Key flow and store in DOUBAO_SPEECH_API_KEY","Verify DOUBAO_SPEECH_VOICE_TYPE is authorized before first batch","Do not send additions.explicit_language to endpoints that reject it"],"tags":["doubao","api-error","auth","quota"],"backgroundTag":null,"analyzedSha":"95e1c3d0ab93482159818560f6a8c8e866b9139f","analyzedAt":"2026-08-15T06:31:20.014Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}