--- name: klingai-common-errors description: 'Diagnose and fix common Kling AI API errors. Use when troubleshooting failed video generation or API issues. Trigger with phrases like ''kling ai error'', ''klingai not working'', ''fix klingai'', ''klingai failed''. ' allowed-tools: Read, Write, Edit, Bash(npm:*), Grep version: 1.18.0 license: MIT author: Jeremy Longshore tags: - saas - kling-ai - debugging - errors compatibility: Designed for Claude Code --- # Kling AI Common Errors ## Overview Complete error reference for the Kling AI API. Covers HTTP status codes, task-level failures, JWT issues, and generation-specific problems with tested solutions. ## HTTP Error Codes | Code | Error | Cause | Solution | |------|-------|-------|----------| | `400` | Bad Request | Invalid parameters, malformed JSON | Validate all required fields; check `model_name` is valid | | `401` | Unauthorized | Invalid/expired JWT token | Regenerate JWT; verify AK/SK; check `exp` claim | | `402` | Payment Required | Insufficient credits | Top up API resource pack or subscription | | `403` | Forbidden | Content policy violation or API disabled | Review prompt against content policy; enable API access | | `404` | Not Found | Invalid task_id or wrong endpoint | Verify task_id; check endpoint path spelling | | `429` | Too Many Requests | Rate limit exceeded | Implement exponential backoff (see pattern below) | | `500` | Internal Server Error | Kling platform issue | Retry after 30s; if persistent, check status page | | `502` | Bad Gateway | Upstream service unavailable | Retry with backoff; typically transient | | `503` | Service Unavailable | System maintenance | Wait and retry; check announcements | ## Task-Level Failures When HTTP returns `200` but `task_status` is `"failed"`: | `task_status_msg` | Cause | Solution | |-------------------|-------|----------| | Content policy violation | Prompt contains restricted content | Remove violent, adult, or copyrighted references | | Image quality too low | Source image is blurry or too small | Use image >= 300x300px, clear and sharp | | Prompt too complex | Too many scene elements | Simplify to 1-2 subjects, clear action | | Generation timeout | Internal processing exceeded limit | Retry; reduce duration from 10s to 5s | | Invalid image format | Unsupported file type | Use JPG, PNG, or WebP | | Mask dimension mismatch | Mask size differs from source | Ensure mask matches source image dimensions exactly | ## JWT Authentication Errors ### Problem: `401` on every request ```python # WRONG — missing headers parameter token = jwt.encode(payload, sk, algorithm="HS256") # CORRECT — include explicit headers token = jwt.encode(payload, sk, algorithm="HS256", headers={"alg": "HS256", "typ": "JWT"}) ``` ### Problem: Token works then fails after 30 min ```python # WRONG — token generated once at import time TOKEN = generate_token() # CORRECT — refresh before expiry class TokenManager: def __init__(self, ak, sk): self.ak, self.sk = ak, sk self._token = None self._exp = 0 @property def token(self): if time.time() >= self._exp - 300: # 5 min buffer payload = {"iss": self.ak, "exp": int(time.time()) + 1800, "nbf": int(time.time()) - 5} self._token = jwt.encode(payload, self.sk, algorithm="HS256", headers={"alg": "HS256", "typ": "JWT"}) self._exp = int(time.time()) + 1800 return self._token ``` ## Rate Limit Handling ```python import time import requests def request_with_backoff(method, url, headers, json=None, max_retries=5): """Retry with exponential backoff on 429 and 5xx errors.""" for attempt in range(max_retries): response = method(url, headers=headers, json=json) if response.status_code == 429: retry_after = int(response.headers.get("Retry-After", 2 ** attempt)) print(f"Rate limited. Retrying in {retry_after}s...") time.sleep(retry_after) continue elif response.status_code >= 500: wait = 2 ** attempt print(f"Server error {response.status_code}. Retrying in {wait}s...") time.sleep(wait) continue response.raise_for_status() return response raise RuntimeError(f"Max retries ({max_retries}) exceeded") ``` ## Diagnostic Checklist When a generation fails, check in order: 1. **Auth valid?** — Test with a simple GET request first 2. **Credits available?** — Check balance in developer console 3. **Model valid?** — Verify `model_name` matches catalog exactly 4. **Parameters valid?** — `duration` must be `"5"` or `"10"` (string, not int) 5. **Prompt clean?** — Remove special characters, keep under 2500 chars 6. **Image accessible?** — For I2V, verify image URL is publicly accessible 7. **Feature exclusivity?** — `image_tail`, `dynamic_masks`, and `camera_control` are mutually exclusive ## Debug Logging ```python import logging logging.basicConfig(level=logging.DEBUG) logger = logging.getLogger("kling") def debug_request(method, url, headers, json=None): """Log request/response for debugging.""" logger.debug(f"→ {method.__name__.upper()} {url}") logger.debug(f"→ Body: {json}") r = method(url, headers=headers, json=json) logger.debug(f"← Status: {r.status_code}") logger.debug(f"← Body: {r.text[:500]}") return r ``` ## Prerequisites - A sandbox workspace, synthetic or rights-cleared diagnostic brief, secret references, approved scope, redaction rules, draft-only destination, and incident owner. ## Instructions 1. Reproduce errors with sandbox fixtures only; do not log authorization headers, prompts, source assets, response bodies, or generated asset URLs. 2. Capture aggregate status, error class, credit use, policy/rights outcome, and task state while verifying redaction and retention controls. 3. Halt the canary and remove temporary drafts on scope, policy, rights, budget, or retention drift; revoke temporary access where appropriate. 4. Store a redacted diagnostic receipt for the approved window and restore the known-good configuration before resuming work. ## Output Produce an error-triage receipt with environment, fixture classification, error class, aggregate status/credit signal, policy/rights/draft-only checks, incident owner, cleanup proof, and rollback reference. Exclude prompts, assets, identities, and credentials. ## Error Handling | Condition | Response | |---|---| | Sensitive material appears in diagnostics | Stop collection, delete the artifact, correct redaction, and rotate/revoke access as needed. | | Policy, rights, budget, or retention drift | Cancel tasks, remove drafts, and require owner review before retrying. | ## Examples `env=ci-sandbox; error=429; retries=backoff; budget=within-cap; policy=pass; destination=draft-only; cleanup=verified` is a valid triage record. ## Resources - [API Reference](https://app.klingai.com/global/dev/document-api/apiReference/model/textToVideo) - [Content Policy](https://app.klingai.com/global/dev/document-api/protocols/paidServiceProtocol) - [Developer Portal](https://app.klingai.com/global/dev) --- Source attribution: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/klingai-pack/skills/klingai-common-errors/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 Intent Solutions Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/klingai-pack/skills/klingai-common-errors/SKILL.md Attribution basis: Source repository record Fields of work: Product Management, Sales, Customer Support Roles: Customer Success Manager, Product Manager, Technical Support Specialties: API, Backend, Design, Word Documents, Frontend, Remotion, Stripe, Testing Tools: Kling Ai Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: b2b2ec700a500b4bd1f1da4159ba96a81fed59851dd93bcf712e1ebd006da828