Why do I still get 429 after topping up?
Why do I still get 429 after topping up?
error.type in the response first:engine_overloaded_error: the service node is under high load (for example, peak-hour capacity pressure). Wait as indicated byRetry-After, reduce concurrency, and retry with exponential backoff. This error is caused by server-side capacity — topping up or upgrading your tier does not resolve it;rate_limit_reached_error: an organization-level concurrency, RPM, TPM, or TPD limit was reached. Reduce request frequency, or see Top-up and Rate Limits to upgrade your tier;exceeded_current_quota_error: insufficient balance, an overdue account, or an expired voucher. Checkavailable_balancewith the balance API and top up.
Why do I get 401, 404, or permission denied?
Why do I get 401, 404, or permission denied?
- Whether the key comes from the product you are calling: Open Platform API keys and Kimi Code keys are not interchangeable;
- Whether the key’s region matches the endpoint: accounts, balances, and keys on platform.kimi.ai are isolated from other regional Kimi platforms;
- Whether the account has available balance, and whether your voucher covers the target model;
- Call
GET /v1/modelswith the same key to confirm the target model is in the returned list; - Whether the model name matches your integration path: direct API calls and Codex use
kimi-k3.1-pro, while Claude Code uses the compatible aliaskimi-k3[1m]. Follow the corresponding integration tutorial; - Clear stale environment variables, proxies, and old configurations in local routing tools such as CC Switch, and confirm which key and endpoint actually take effect.
A third-party agent or IDE still fails after configuring Kimi — how do I locate the problem?
A third-party agent or IDE still fails after configuring Kimi — how do I locate the problem?
- Call the Kimi API directly with the same key, endpoint, and model (see the cURL example in the Kimi K3.1 Pro quickstart);
- If the direct call fails, resolve balance, authentication, model permission, or request parameter issues first;
- If the direct call succeeds but the third-party tool still fails, check the tool’s logs — focus on protocol conversion, streaming responses, timeout settings, and automatic retries;
- When using Claude Code, Codex, OpenCode, and similar tools, follow the corresponding tutorial — model names and configuration may differ;
- Keep the client version, time of occurrence,
request_id, actual request endpoint, and redacted logs for further troubleshooting.
Why was I charged when the agent showed no result?
Why was I charged when the agent showed no result?
- The HTTP status code and
request_idof the request; - The
usagefield in the API response; - Whether the client retried automatically, spawned sub-agents, or looped tool calls;
- The usage dashboard and billing details in the console;
- Timeout and connection errors in the client logs.
request_id, model, client version, redacted logs, and billing details.How do I review billing details and report unexpected charges?
How do I review billing details and report unexpected charges?
usage returned by the API by time, project, model, and request_id.If you need help from the platform team, prepare: organization ID, project name, time of occurrence (with time zone), request_id, model name, client and version, redacted logs, and relevant billing or export records, then email [email protected].Does Context Caching require manual configuration?
Does Context Caching require manual configuration?
5m TTL; hits are then billed at the cached-input price.That said, choose the TTL based on your request interval: if requests may be more than 5 minutes apart, pass prompt_cache_options.ttl to select 1h so the cache does not expire between requests and cause repeated write charges; the default 5m is enough for rapid back-and-forth. Writes incur a one-time cache write charge, billed by the selected TTL.Keeping the initial prefix stable (system prompt, tool definitions, long documents) helps subsequent requests hit the cache. Modifying the prefix may reduce the hit rate. See Context Caching.What do I need to use Kimi K3.1 Pro?
What do I need to use Kimi K3.1 Pro?
How do I choose a reasoning effort level for Kimi K3.1 Pro?
How do I choose a reasoning effort level for Kimi K3.1 Pro?
reasoning_effort field: low, high, or max (default max). Use higher levels for more complex tasks; lower levels reduce latency and token consumption for simple tasks.See Reasoning Effort for details and examples.How do I turn off Kimi K3.1 Pro's chain-of-thought?
How do I turn off Kimi K3.1 Pro's chain-of-thought?
reasoning_effort to low to reduce the reasoning effort. See Reasoning Effort.Can I try the models before topping up?
Can I try the models before topping up?
Why does the model repeatedly call the same tool when using tool_calls?
Why does the model repeatedly call the same tool when using tool_calls?
choice.message as is, match tool_call_id, assemble streamed tool_calls correctly). If the repetition persists, add client-side repeated-call detection and append system prompt reminders. See How to fix repeated tool calls.Why are API results different from Kimi Assistant results?
Why are API results different from Kimi Assistant results?
Does the Kimi API have Kimi Assistant's "web browsing" feature?
Does the Kimi API have Kimi Assistant's "web browsing" feature?
web-search tool or standalone REST APIs. You can also integrate your own or a third-party search service through standard tool_calls.- Your application executes tool calls through the Formula API: Use the official
web-searchtool. Your application retrieves the tool declaration and executes search tool calls through the Formula API, then returns the results to the model using the standardtool_callsflow. See Use Official Tools with the Kimi API. - Control search and fetching in your application: Call
POST /v1/tools/searchorPOST /v1/tools/search_proto search the web, andPOST /v1/tools/fetchto fetch a specific page. You can process the results before providing them to the model. See Web Search Best Practices. - Integrate your own or a third-party search service: Expose your search or page-fetching service as a standard
functiontool and declare it intools. After the model generates the call arguments, your application performs the search or page fetch and returns the result in arole: "tool"message. See Use the Kimi API for Tool Calls.
The content returned by the Kimi API is incomplete or truncated
The content returned by the Kimi API is incomplete or truncated
choice.finish_reason in the response body. If the value is length, it means the number of tokens generated by the current model exceeded the max_completion_tokens parameter in the request. In this case, the Kimi API only returns up to max_completion_tokens tokens, and any extra content is discarded.When you encounter finish_reason=length, and you want the Kimi model to continue from the previous response, you can use Partial Mode. For details, see:Use Partial Mode with the Kimi APITo avoid finish_reason=length, increase max_completion_tokens appropriately. Use the estimate-token-count API to calculate the input tokens, then subtract them from the selected model’s context window to determine the remaining context capacity for the request. See the Model Parameter Reference for each model’s context window.What is the output length of the Kimi model?
What is the output length of the Kimi model?
kimi-k3.1-pro and kimi-k3 support a 1M-token context window, and max_completion_tokens defaults to 131072. The available output length is also limited by the input tokens in the request.How many Chinese characters does the Kimi model support?
How many Chinese characters does the Kimi model support?
File extraction is inaccurate, or images cannot be recognized
File extraction is inaccurate, or images cannot be recognized
purpose="image".For the complete list of supported file formats and how to use image understanding, see:Files Upload APIUse Vision ModelsWhen using the files API, I want to reference file content with file_id
When using the files API, I want to reference file content with file_id
file_id.Error: content_filter: The request was rejected because it was considered high risk
Error: content_filter: The request was rejected because it was considered high risk
content_filter error.If you call the API through a third-party platform or tool, first confirm that the error was actually returned by the Kimi API: third-party platforms may apply their own content safety policies and error wording, so their messages do not necessarily come from the Kimi API. Check the third-party platform’s logs as well.The platform cannot disclose the exact safety rules that were triggered. You can try narrowing the request scope, removing content that may cause false positives, and retry.The TPM or RPM limit in the error message does not match my account tier
The TPM or RPM limit in the error message does not match my account tier
rate_limit_reached_error while using the Kimi API, for example:api_key for the current account. In most cases, this mismatch is caused by using the wrong api_key, such as accidentally using a key provided by another user or mixing up keys across multiple accounts.Error: model_not_found
Error: model_not_found
base_url=https://api.moonshot.ai/v1. The model_not_found error is usually caused by using the OpenAI SDK without setting base_url, which sends the request to OpenAI servers instead. OpenAI then returns the model_not_found error.The Kimi model makes numerical calculation errors
The Kimi model makes numerical calculation errors
tool_calls) to provide calculator functionality to the Kimi model. For more information, see our tool calling guide:Use the Kimi API for Tool Calls (tool_calls)The Kimi model cannot answer today's date
The Kimi model cannot answer today's date
kimi-k3.1-pro by default. K3.1 Pro configures reasoning effort with the top-level reasoning_effort request field (supports "low" / "high" / "max", default "max"). To use another model such as kimi-k3.1-pro-highspeed, replace the model field and adjust the parameter configuration for that model. See the Model Parameter Reference.- python
- node.js
How do I handle errors without using an SDK?
How do I handle errors without using an SDK?
- python
- node.js
Why do some requests respond quickly while others respond slowly when the prompts are similar?
Why do some requests respond quickly while others respond slowly when the prompts are similar?
stream=True and observe the time to first token, abbreviated as TTFT. In normal cases, when prompt lengths are similar, TTFT should not vary significantly.I set max_completion_tokens=2000 to make Kimi output 2,000 characters, but the output is shorter
I set max_completion_tokens=2000 to make Kimi output 2,000 characters, but the output is shorter
Note:Themax_tokensis deprecated. Please usemax_completion_tokensinstead. The two fields have the same meaning.
max_completion_tokens parameter means: when calling /v1/chat/completions, it specifies the maximum number of tokens the model is allowed to generate. Once the number of generated tokens exceeds max_completion_tokens, the model stops generating the next token.max_completion_tokens is used to:- Help the caller determine which model to use. For example, when
prompt_tokens + max_completion_tokens <= 256 * 1024, you can choosekimi-k3.1-pro. - Prevent the Kimi model from generating too much unexpected content in unusual cases, which could cause extra cost. For example, the model might repeatedly output whitespace.
max_completion_tokens does not tell the Kimi model how many tokens to output. In other words, max_completion_tokens is not used as part of the prompt input to the Kimi model. If you want the model to output a specific number of characters, use these general approaches:- For outputs under 1,000 characters:
- Clearly specify the desired character count in the prompt.
- Manually or programmatically check whether the output length meets expectations. If not, tell the model in a second round that the output is too long or too short, then ask it to generate a new version.
- For outputs over 1,000 characters or much longer:
- Split the expected output by structure or chapter, create a template, and use placeholders to mark where the model should fill in content.
- Ask the Kimi model to fill each placeholder one by one, then assemble the complete long-form text.
I only made one request in a minute, but triggered Your account reached max request
I only made one request in a minute, but triggered Your account reached max request
Certain errors are automatically retried 2 times by default, with a short exponential backoff. Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors are all retried by default.This retry mechanism retries 2 times by default when an error occurs, for a total of 3 requests. In unstable network conditions or other cases that may cause request errors, using the OpenAI SDK can expand one request into 2 or 3 requests. All of these requests count toward your RPM quota.Note: For users on a
tier0 account using the OpenAI SDK, one failed request may consume the entire RPM quota because of the default retry mechanism.I used base64 encoding for my text content to make transmission easier
I used base64 encoding for my text content to make transmission easier
base64 can cause massive token consumption. If your file type is supported by our /v1/files API, upload the file through the files API and extract its content there.For binary files or files in other encoded formats, the Kimi model currently cannot parse the content. Do not add this content to the context.Why can't I use a key from another Kimi platform on platform.kimi.ai?
Why can't I use a key from another Kimi platform on platform.kimi.ai?
401 invalid_authentication_error. If you receive a 401 error, first check whether you are using a key from the wrong platform.- International open platform
base_url: https://api.moonshot.ai/v1