Meaning: The request parameters are invalid, so the server cannot process the request.

Common causes:

• The request body has an invalid format
• A required parameter is missing
• A parameter has the wrong type
• The context length exceeds the model's limit
• Parameters sent by a third-party tool use an incompatible format
• Video generation parameters are invalid
• The request format is incompatible with a tool such as Codex

Solutions:

• Check that all required parameters are included
• Validate the JSON format
• Shorten the prompt and conversation history
• Start a new conversation and try again
• Check video generation parameters such as FPS, duration, resolution, and aspect ratio
• When using Codex or another third-party tool, check and adjust the request format or try another Agent

Meaning: Authentication failed. The request could not be authenticated.

Common causes:

• The API Key is incorrect
• The API Key has expired
• The API Key is configured incorrectly
• The Authorization field is missing from the request Header
• The API Key belongs to another account

Solutions:

• Check that the complete API Key was copied
• Confirm that the API Key is still valid
• Generate a new API Key and try again
• Check that the request Header contains the API Key correctly
• Confirm that the API Key belongs to the account currently in use

Meaning: The account balance or available quota is insufficient to complete the request.

Common causes:

• The account balance is insufficient
• The Token Plan quota is insufficient
• The current request exceeds the available quota
• The subscription is in an abnormal state
• A top-up or subscription has not taken effect yet

Solutions:

• Check the account balance
• Check the Token Plan or subscription status
• Add funds or upgrade the plan
• Reduce the cost of the request, for example by shortening the context or lowering image or video generation specifications
• Wait for the top-up or subscription to take effect, then try again

Meaning: The current account or API Key does not have permission to access the requested resource.

Common causes:

• The API Key does not have access to the requested model
• The account has not been granted access to the requested model
• A subscription, user group, or permission change has not taken effect yet
• The request source was blocked by a security rule
• The IP address, region, or network environment is restricted

Solutions:

• Check whether the account has permission to access the model
• Check whether the API Key belongs to the correct account
• Confirm that the subscription, user group, or permission change has taken effect
• Try a different network environment
• If you have confirmed access but the problem persists, contact technical support

Meaning: The requested API address, path, or resource does not exist.

Common causes:

• The API address is incorrect
• The Base URL is configured incorrectly
• The request path is incorrect
• A third-party tool added /v1 more than once
• The model name is incorrect
• The requested resource does not exist

Solutions:

• Check that the API address is correct
• Check that the Base URL is correct
• Check whether /v1 was added more than once in the third-party tool configuration
• Check that the model name is correct
• Check that the API path follows the documentation

Meaning: The current API endpoint does not support the request method being used.

Common causes:

• The HTTP method is incorrect
• GET was used when POST is required
• POST was used when GET is required
• The request method is configured incorrectly in a third-party tool

Solutions:

• Check the required request method in the API documentation
• Confirm that the endpoint uses the correct method, such as GET or POST
• Update the request method configuration in the third-party tool
• Try again after changing the request method

Meaning: The request timed out. The server could not finish processing it within the allowed time.

Common causes:

• The local network is unstable
• The request is too large
• The context is too long
• An image, video, or long-text task takes too long to process
• The client timeout is too short

Solutions:

• Retry the request
• Check the local network environment
• Shorten the input or reduce the context length
• Lower the image or video generation specifications
• Increase the client timeout as appropriate
• Add retry logic for long-running tasks

Meaning: The request conflicts with the current state of a resource or task.

Common causes:

• A task was submitted more than once
• The same request is already being processed
• The current resource state does not allow this operation
• A third-party tool sent the same request more than once

Solutions:

• Avoid submitting the same request repeatedly within a short period
• Wait for the current task to finish before trying again
• Check the task status
• Add duplicate-submission protection to the client
• If the task has finished, check the task history first

Meaning: The request body is too large for the server to process.

Common causes:

• The request body is too large
• The input context is too long
• A base64 image is too large
• An uploaded file or image exceeds the limit
• Too much content was submitted in one request

Solutions:

• Compress the request content
• Reduce the context length
• Submit the content in batches
• Reduce the size or resolution of uploaded images
• For images, use a public URL instead of sending a large base64 payload

Meaning: The file format or Content-Type in the request is not supported.

Common causes:

• The uploaded file format is not supported
• The Content-Type in the request Header is incorrect
• The image, audio, or video format does not meet the API requirements
• A third-party tool set an incorrect Content-Type automatically

Solutions:

• Check the uploaded file format
• Confirm that the Content-Type is correct
• For images, use a common format such as PNG, JPG, JPEG, or WEBP
• For audio or video, use a format supported by the API
• Convert the file format and try again

Meaning: The request format is valid, but a parameter value does not meet the model or API requirements.

Common causes:

• A parameter value is invalid
• Image editing parameters are invalid
• Video generation parameters are invalid
• The seed, resolution, aspect ratio, FPS, or another parameter is outside the allowed range
• The image URL in an image-to-image request cannot be accessed
• The base64 format is invalid
• The requested image or video size does not meet the constraints

Solutions:

• Check the error message for the specific parameter involved
• Check that the image or video generation parameters are valid
• Check that the seed value is within the allowed range
• Check that the image URL is publicly accessible
• Check that the base64 content is complete and valid
• Update the parameters and try again

Meaning: The request rate is too high and exceeds the current account's RPM limit.

Common causes:

• The RPM limit was exceeded
• The account or user group triggered the current request limit
• There are too many concurrent requests
• Too many repeated requests were sent within a short period
• Automatic retries are happening too frequently

Solutions:

• If the response includes Retry-After, wait for that period; otherwise, use exponential backoff
• Reduce the request rate
• Limit the number of concurrent requests
• Add an appropriate retry strategy
• Avoid repeated requests within a short period
• Contact platform support if you need to confirm the limits that apply to the account

Meaning: The request Header is too large for the server to process.

Common causes:

• The Header contains too much data
• The Authorization information is invalid
• A Cookie or custom Header is too large
• A third-party tool added too many Headers automatically

Solutions:

• Reduce the size of the request Header
• Check that the Authorization field is correct
• Remove unnecessary Cookies or custom Headers
• Reconfigure the request Headers in the third-party tool
• Try again after updating the Headers

Meaning: The client closed the connection before the request completed.

Common causes:

• The client disconnected after timing out
• A browser or tool interrupted the request
• The local network changed or disconnected
• A long-running task took too long to finish
• A third-party tool canceled the request early

Solutions:

• Send the request again
• Check the stability of the local network
• Increase the client timeout
• Avoid closing the page or interrupting the tool while the task is running
• Use an asynchronous task or polling for long-running operations

Meaning: The server encountered an internal error, or the request parameters triggered a service error.

Common causes:

• The request parameters are invalid
• The image generation size does not meet the requirements
• The video generation size does not meet the requirements
• The context parameter is not configured in OpenClaw
• The upstream service is temporarily unavailable

Solutions:

• Check the request parameters
• Check dimensions, duration, and other generation parameters against the API requirements of the selected model
• Check the context parameter in the OpenClaw settings
• Update the parameters and try again
• If the problem remains after several retries, send the error details to technical support

Meaning: The gateway or proxy did not receive a valid response from the upstream service.

Common causes:

• A local network problem
• A DNS resolution problem
• A proxy configuration problem
• An unstable network connection
• A temporary upstream service issue

Solutions:

• Check the local network environment
• Try another network
• Change the DNS settings
• Check the proxy configuration
• Try again later
• If necessary, ask an AI assistant or technical specialist to help inspect the local network configuration

Meaning: The service is temporarily unavailable, or the request failed because of a third-party tool configuration issue.

Common causes:

• The model name is incorrect
• The model list could not be retrieved
• No fallback model is selected
• Routing is not enabled
• A third-party tool sent the request to the wrong model
• The service is temporarily unavailable

Solutions:

• Check that the model name is correct
• Retrieve the model list again
• Select a fallback model
• Enable routing
• Check that the test-model and backup-model settings in the third-party tool are configured correctly
• Try again later

Meaning: The gateway timed out while waiting for a response from the upstream service.

Common causes:

• The upstream model timed out
• An image, video, or long-context task takes too long to process
• The network connection is unstable
• Service load is high during peak periods
• The request is too complex

Solutions:

• Try again later
• Shorten the input
• Lower the image or video generation specifications
• Reduce the number of concurrent requests
• Increase the client timeout as appropriate
• Add retry logic for long-running tasks

Meaning: An unknown error occurred, usually related to the network connection, gateway behavior, or a temporary upstream service issue.

Common causes:

• A network connection problem
• A temporary upstream service issue
• A proxy configuration problem
• A DNS configuration problem
• The gateway returned a nonstandard error

Solutions:

• Retry the request
• Check the local network environment
• Check the proxy configuration
• Check the DNS configuration
• Try again later
• If the problem persists, send the complete error message to technical support

Meaning: The gateway timed out while connecting to the upstream service.

Common causes:

• The network connection timed out
• A connection problem occurred between the gateway and the upstream service
• A local network problem
• A proxy configuration problem
• A DNS configuration problem

Solutions:

• Retry the request
• Check the local network
• Check the proxy configuration
• Change the DNS settings
• Try a different network environment
• Try again later

Meaning: The connection was established, but the upstream service took too long to process the request.

Common causes:

• A long-context task takes too long
• An image generation task takes too long
• A video generation task takes too long
• Service load is high
• The request is too complex

Solutions:

• Try again later
• Reduce the request complexity
• Shorten the context
• Lower the generation specifications
• Reduce the number of concurrent requests
• Use an asynchronous task or polling for long-running operations