Skip to content
Documentation
Dashboard
API referenceQwen: errors and boundaries

Qwen: errors and boundaries

Public Qwen codes, the queue, safe retries, and unsupported inputs.

Read the HTTP status and error.code first. Messages wraps errors in an Anthropic-compatible type: "error" object; Chat Completions and Responses use an OpenAI-compatible error object. The codes and actions below are the same in every shape.

Fix the request

HTTP / codeCauseAction
400 invalid_jsonThe body is not a JSON object.Fix the JSON and send content-type: application/json.
400 unsupported_parameterThe field's value changes the answer, and Qwen does not support that setting: for example a non-empty stop, n greater than 1, or logprobs.Remove the field named in error.param. Sampling parameters such as temperature and top_p are accepted and do not affect the answer.
400 invalid_stream / invalid_stream_optionsstream is not a boolean, or stream_options has a field other than include_usage.Send a boolean and only include_usage.
400 messages_required / invalid_input / max_tokens_requiredmessages is missing (input in Responses); in Messages, max_tokens is missing.Send a non-empty history and, in Messages, an output budget.
400 invalid_token_limit / conflicting_token_limitsThe output limit is below 1 or above 131,072, or both max_tokens and max_completion_tokens were sent.Keep one field. A value above the model's limit (65,536 for the Plus models and qwen3.5-omni-plus, 131,072 for the others) is reduced to that limit by the gateway.
400 invalid_tools / unsupported_tool_type / invalid_tool_schematools is not an array of objects, the type is not function, or the parameter schema is invalid.Fix the function declaration for the selected API.
400 unverified_server_toolMessages requested a server tool other than web_search_* and web_fetch_*.Use a client function; Qwen decides on search itself.
400 stored_responses_unsupportedResponses included store: true or previous_response_id: Qwen does not store responses.Remove these fields and send the whole history in input.
400 background_unsupportedResponses included background: true.Remove background: the answer arrives as a regular response or a stream.
400 invalid_tool_choicetool_choice requires a function that is not in tools.Send auto, none, required, or the name of a declared function.
400 unsupported_image / invalid_image / inline_media_requiredAn image for qwen3.7-max, a file that is not PNG, JPEG, or WEBP, or a URL instead of base64 (a URL or file_id in Messages and file_id in Chat receive 400 unsupported_parameter).Choose a model with image input and send the file in the request body.
400 unsupported_media / invalid_attachment / invalid_document / document_encoding_unsupportedThe document is not PDF, TXT, CSV, Markdown, or JSON, the data is not base64, the PDF is damaged, has more than 200 pages, or too much text, or a text file is not UTF-8.Send a supported file in the request body; split a large PDF into parts.
400 effort_unsupportedMessages included output_config.effort.Remove output_config: Qwen does not accept an effort level.
404 model_not_foundThe ID is not one of the seven Qwen IDs, or /qwen/v1 received another family's model.Fetch GET /qwen/v1/models and send an exact ID.
413 context_too_largeInput exceeds the model context, or the request text is larger than 2 MiB.Shorten the history or lower the output budget.
413 attachments_too_large / too_many_imagesThe request's attachments are too large together, or the history has more than 32 images.Shrink the attachments, remove old ones from the history, or start a new conversation.
413 request_body_too_largeThe request body exceeds 12 MiB; base64 makes files about a third larger, so a file above 9 MiB receives this refusal.Shrink the attachments or send them in separate requests.

Key, balance, and limits

HTTP / codeAction
401 missing_api_keyNo key was sent: add the Authorization: Bearer gd-… or x-api-key header.
401 invalid_api_keyCheck the full active gd-… value and the Authorization: Bearer … header.
402 insufficient_creditCheck the key's shared balance.
402 request_reserve_exceeds_creditLower the output budget or add credit; the final debit still uses the estimate of the actual answer.
403 api_key_pausedQwen or the whole key is paused in the dashboard. Resume it.
403 model_not_allowedThe model is not allowed in the key settings. Allow it in the dashboard.
429 customer_hour_limit / customer_day_limitA dashboard spending limit was reached. Change the limit or wait for the window to end.
429 client_key_rate_limitWait at least the Retry-After interval and retry once.

Queue and temporary availability

HTTP / codeMeaningRetry
429 queue_timeoutNo Qwen account became free within 30 seconds.Retry-After: 30. Add jitter and avoid hidden parallel retries.
429 provider_at_capacityEvery Qwen model that accepts this request is busy.Retry-After: 5. Use backoff.
503 qwen_unavailableQwen is temporarily unavailable.Retry-After: 30. Retry later.
503 model_unavailableThe selected Qwen model is currently unavailable.Retry-After: 30. Choose another Qwen model or retry later.
502 generation_timeoutGeneration took longer than 10 minutes.Shorten the task or the output budget and send a new request.
502 with another codeQwen did not finish the answer or could not continue the conversation.Retry the request; if it persists, send the code to support.

Diagnostics without secrets

  • Keep the UTC time, endpoint, model, HTTP status, and error.code.
  • Include request_id from the response or the ID from the dashboard.
  • Do not send the key, full prompt, model output, or image contents.
  • Check the status page and then contact @Guard_help.

Documentation sections

On this page