The envelope and fields are the same as for every family — see Error codes: Russian text, code, action, request_id and the [code · req_…] tail in the text. Below are only the Kimi-specific codes.
| HTTP / code | Meaning | What to do |
|---|---|---|
400 invalid_json / invalid_messages / messages_required / invalid_request | invalid body or parameter | fix the request; do not retry it unchanged |
400 invalid_stream | the stream field is not a boolean | send true or false |
401 | missing, invalid, or revoked key | check Bearer authentication |
402 request_reserve_exceeds_credit | balance cannot cover the reserve for the input plus the largest possible answer | shorten the request, reduce max_tokens, or top up |
404 model_not_found | unknown Kimi model ID | copy one of the four exact IDs |
413 request_too_large | the request exceeds the allowed size | shorten the message history or the attachments |
429 client_key_rate_limit | too many requests from this key | retry no earlier than Retry-After, usually one second |
429 kimi_queue_full | the request queue is temporarily full | retry with a delay |
429 rate_limit_exceeded | a short Kimi frequency limit | wait 60–90 seconds and retry |
429 kimi_daily_spend_limit | the daily Kimi spend limit on this key is already used up | raise the limit in the bot or wait; Retry-After is one day |
429 kimi_hourly_spend_limit | the hourly Kimi spend limit on this key is already used up | raise the limit in the bot or wait; Retry-After is one hour |
429 kimi_daily_reserve_limit | what is left of the daily limit does not cover the reserve for this particular request | lower max_tokens and the request itself, or raise the limit |
429 kimi_hourly_reserve_limit | what is left of the hourly limit does not cover the reserve for this particular request | lower max_tokens and the request itself, or raise the limit |
400 invalid_request with the text «Kimi отклонил запрос. Ответ поставщика: …» | Kimi itself rejected your request (for example temperature other than 1 on /v1/messages); its explanation follows the Russian lead-in verbatim | fix the field as explained; nothing was charged |
503 kimi_unavailable as a frame inside the stream | the Kimi node dropped the answer after the SSE stream had started | retry; the stream is closed with an error frame and data: [DONE], not a connection drop |
502 kimi_model_mismatch | the response did not match the selected model; you pay nothing | send the [code · req_…] tail to support |
503 kimi_billing_unavailable | Kimi billing is temporarily unavailable | retry later; the request was not sent and nothing was charged |
503 kimi_unavailable | Kimi is temporarily unavailable | retry later |
403 kimi_agent_not_allowed | Kimi For Coding serves only the coding agents on its list (Kimi CLI, Claude Code, Roo Code, Kilo Code) and refused the agent named in the system prompt | Use a supported client such as Roo Code / Kilo Code. Do not remove or impersonate the agent name to bypass the restriction; retrying alone will not help. |
One status code covers seven unrelated reasons, and they are not cured the same way. The first three are temporary: wait and retry. The last four are your own spend limits, and waiting will not help until the limit is changed or the window moves.
error.code | Who set the limit and what Retry-After says |
|---|---|
client_key_rate_limit | Guard's own limiter on how often one key may send requests. Retry-After is one second |
kimi_queue_full | the queue to the Kimi nodes is temporarily full. Retry-After is one second |
rate_limit_exceeded | Kimi's own short frequency limit, separate from plan quota and from your balance. Retry-After says one second, but in live checks it cleared after about 80 seconds while barely touching plan quota |
kimi_daily_spend_limit | the daily Kimi spend limit on this key is fully used. Retry-After is one day |
kimi_hourly_spend_limit | the hourly Kimi spend limit on this key is fully used. Retry-After is one hour |
kimi_daily_reserve_limit | the daily limit is not used up yet, but what is left does not cover the reserve for this request. Retry-After is one day |
kimi_hourly_reserve_limit | the hourly limit is not used up yet, but what is left does not cover the reserve for this request. Retry-After is one hour |
Kimi spend limits are counted separately from the Claude ones and over a sliding window: not since midnight, but over the last 24 hours and the last hour. The sum includes both settled requests and reserves that are still open. The limit itself is changed in the bot.
The file API uses a different error envelope: the code is in detail.error.code, not in error.code as on /v1/chat/completions. Errors about input_file references come from the chat request itself and stay in the usual error.code.
| HTTP / code | Meaning | What to do |
|---|---|---|
415 unsupported_media_type | the Content-Type header is not multipart/form-data | send a form, not JSON |
400 invalid_multipart | the body did not parse as multipart/form-data, it carries no file field, or the form carries more than one additional field | send one file part in the file field and at most one field beside it |
400 invalid_file_purpose | purpose is not one of the accepted values | send user_data, file-extract, or assistants |
400 empty_file | a zero-length file | send a non-empty file |
400 invalid_file_reference | file_id does not look like a file identifier | use the id from the upload response |
402 insufficient_credit | the key has zero remaining credit; every file API call answers this way, DELETE included | top the key up, or wait for the files to expire after 24 hours |
404 file_not_found | the file is gone, expired, or belongs to another key | upload it again with the same key |
404 not_found | the key has no Kimi family, so the file surface is closed for it | check Kimi access; retrying changes nothing |
413 file_too_large | the file is larger than 10 MiB | shrink the file |
413 file_count_quota_exceeded / file_storage_quota_exceeded | the key already holds 20 files or 50 MiB of occupied space | delete unused ones with DELETE /v1/files/{file_id} |
413 file_reference_limit / file_context_too_large | more than 20 references in one request, or a finished document block above 2 MiB | reference fewer documents |
413 extracted_text_too_large | more than 2 MiB of extracted text | split the document |
413 document_section_limit | plain text split into more than 1000 sections | split the file |
413 too_many_sections | the same thing for PDF, .docx, .xlsx, and .pptx — their code is a different one | split the document |
413 pdf_page_limit | the PDF has fewer than one or more than 200 pages | split the PDF into 200-page parts |
413 office_sheet_limit / office_slide_limit | more than 200 sheets in .xlsx, or more than 500 slides in .pptx | split the workbook or the deck |
413 office_row_limit / office_cell_limit / office_cell_too_large | more than 20,000 rows on a sheet, more than 200,000 cells in an .xlsx workbook or in a single .docx table, or an .xlsx cell longer than 32,768 characters | shrink the table, or export it to .csv in parts |
413 office_block_limit | more than 50,000 blocks in .docx, or shapes in .pptx | split the document |
413 file_size_limit | the parser received an empty file, or more than 10 MiB | send a non-empty file within 10 MiB |
415 unsupported_file_type | the extension or content type is outside the supported list | convert to one of the eight formats |
415 invalid_document / invalid_pdf / invalid_office_document | the file does not read as a document of the declared format | re-save the file |
413 office_document_too_large / office_document_entry_limit / office_document_compression_ratio | a .docx, .xlsx, or .pptx file unpacks into an archive that is too large or too dense | re-save the document without nested archives or spare objects |
415 encrypted_document_unsupported | the document is password-protected | remove the password before uploading |
415 invalid_text_encoding | the text file is not UTF-8 | re-save it as UTF-8 |
415 invalid_text_document | the text file carries control bytes other than tab and newline | strip the binary parts, or upload the file as a document of a supported format |
415 document_parse_timeout | the document did not finish parsing in time | simplify or shrink the document |
429 file_rate_limit | too many calls to the file API | retry no earlier than Retry-After |
503 document_parser_unavailable / file_storage_unavailable | document parsing or storage is temporarily unavailable | retry later |
503 file_encryption_unavailable / file_decryption_failed / file_integrity_failed / file_id_collision | a rare fault on our storage side: the file could not be encrypted, decrypted, validated, or given an identifier | retry later; if it repeats, save the request ID and contact support |
| HTTP / code | Meaning | What to do |
|---|---|---|
400 invalid_managed_service_request | the body does not carry exactly the one expected field, or it did not parse as JSON at all | keep only query, or only url, and check that the body is valid JSON |
400 invalid_search_query | query is empty or longer than allowed | shorten the query |
400 / 422 invalid_fetch_url | the address is not public http/https, or it does not resolve to an external address | send a plain public link |
402 insufficient_credit | the key has zero remaining credit | top the key up |
404 route_not_found | the key has no Kimi family | check Kimi access; retrying changes nothing |
422 managed_service_request_failed | the most frequent refusal: a dead link, a paywall, bot protection, or a 403, 404, or 500 answer from the site itself. This response deliberately carries no Retry-After | use another address or another query; repeating the same one will not help |
429 client_key_rate_limit / kimi_queue_full | too frequent, or the queue is full | retry no earlier than Retry-After |
502 managed_service_invalid_response | an answer arrived but did not parse: not UTF-8, or the wrong envelope. No Retry-After | retry once; if it repeats, pick another address |
503 managed_service_unavailable | two different causes under one code: the provider answered 408, 429, or 503, or the page turned out to be larger than 2 MiB and the transport cut it off. Retry-After: 1 is present in both cases | in the first case retry after Retry-After; in the second a retry is useless — the page will not get smaller |
503 kimi_unavailable | the whole Kimi surface is temporarily unavailable | retry later |
Guard checks the model in the response against the one you requested. If they do not match, the response is not handed to you at all — you get 502 kimi_model_mismatch instead.
You pay nothing for such a request. The reserve is released in full, no spend row is written, and the request will not appear in the key's report. The counters the provider sent do not move your balance, however large they claim to be: that cost is ours, not yours. Streaming behaves the same way: the start of the stream is held back until a frame carries the model name, so nothing reaches you when it does not match.
Retrying right away is fine: the node that answered off-contract is marked failed and the next attempt goes to another one. If 502 kimi_model_mismatch keeps repeating, save the request ID and contact support.