Agnes API Common Error Codes and Solutions
400 Bad Request
Meaning: The request parameters are invalid, and the server cannot process the request. Common causes:- Invalid request body format
- Missing required parameters
- Incorrect parameter types
- Context length exceeds the model limit
- Incompatible parameter format from third-party tools
- Incorrect video generation parameters
- Request format incompatibility with tools such as Codex
- Check whether all required parameters are included
- Verify that the JSON format is valid
- Compress 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 third-party tools such as Codex, check and adjust the request format, or try another Agent
401 Unauthorized
Meaning: Authentication failed. The request did not pass identity verification. Common causes:- Incorrect API Key
- Expired API Key
- API Key is not configured correctly
- Missing Authorization field in the request Header
- API Key belongs to a different account
- Check whether the API Key was copied completely
- Confirm that the API Key is still valid
- Regenerate the API Key and try again
- Check whether the API Key is correctly included in the request Header
- Confirm that the API Key belongs to the account currently in use
402 Payment Required
Meaning: The account balance or available quota is insufficient to complete the request. Common causes:- Insufficient account balance
- Insufficient Token Plan quota
- The current request exceeds the available quota
- Abnormal subscription status
- Top-up or subscription has not taken effect yet
- Check the account balance
- Check the Token Plan or subscription status
- Top up or upgrade the plan
- Reduce the cost of a single request, such as shortening the context or lowering image/video generation specifications
- Retry after the top-up or subscription becomes active
403 Forbidden
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
- Enterprise verification, subscription, or permission status has not taken effect
- The request source is blocked by security rules
- IP address, region, or network environment is restricted
- Check whether the account has permission to access the model
- Check whether the API Key belongs to the correct account
- Confirm whether the subscription or enterprise verification status has taken effect
- Try again with another network environment
- If permission is confirmed but the issue persists, contact technical support
404 Not Found
Meaning: The requested API address, path, or resource does not exist. Common causes:- Incorrect API address
- Incorrect Base URL configuration
- Incorrect request path
/v1is duplicated by a third-party tool- Incorrect model name
- The requested resource does not exist
- Check whether the API address is correct
- Check whether the Base URL is correct
- Check whether
/v1is duplicated in the third-party tool configuration - Check whether the model name is correct
- Check whether the API path follows the documentation
405 Method Not Allowed
Meaning: The current API endpoint does not support the request method being used. Common causes:- Incorrect HTTP method
- GET is used when POST is required
- POST is used when GET is required
- Incorrect request method configuration in a third-party tool
- Check the required request method in the API documentation
- Confirm that the endpoint is using the correct method, such as GET or POST
- Update the request method configuration in the third-party tool
- Retry after modifying the request method
408 Request Timeout
Meaning: The request timed out. The server could not complete processing within the allowed time. Common causes:- Unstable local network
- Request content is too large
- Context is too long
- Image, video, or long-text tasks take too long to process
- Client timeout setting is too short
- Retry the request
- Check the local network environment
- Shorten the input content or reduce the context length
- Lower image or video generation specifications
- Increase the client timeout setting appropriately
- Add retry logic for long-running tasks
409 Conflict
Meaning: The request conflicts with the current resource or task state. Common causes:- Duplicate task submission
- The same request is already being processed
- The current resource state does not allow this operation
- A third-party tool repeatedly sends the same request
- Avoid submitting the same request repeatedly within a short period
- Wait for the current task to complete before retrying
- Check the task status
- Add duplicate-submission protection on the client side
- If the task has already completed, check the task history first
413 Payload Too Large
Meaning: The request body is too large for the server to process. Common causes:- Request body is too large
- Input context is too long
- base64 image is too large
- Uploaded file or image exceeds the limit
- Too much content is submitted in a single request
- Compress the request content
- Reduce the context length
- Submit content in batches
- Reduce the uploaded image size or resolution
- For images, use a public URL instead of sending a large base64 payload
415 Unsupported Media Type
Meaning: The file format or Content-Type in the request is not supported. Common causes:- Unsupported uploaded file format
- Incorrect Content-Type in the request Header
- Image, audio, or video format does not meet API requirements
- A third-party tool automatically sets an incorrect Content-Type
- Check the uploaded file format
- Confirm whether the Content-Type is correct
- For images, use common formats such as PNG, JPG, JPEG, or WEBP
- For audio or video, use formats supported by the API
- Convert the file format and retry
422 Unprocessable Entity
Meaning: The request format is valid, but the parameter values do not meet the model or API requirements. Common causes:- Invalid parameter values
- Abnormal image editing parameters
- Abnormal video generation parameters
- seed, resolution, aspect ratio, FPS, or other parameters exceed the allowed range
- Image URL in an image-to-image request cannot be accessed
- Invalid base64 format
- Image or video generation size does not meet the required constraints
- Check the specific parameter hint in the error message
- Check whether image or video generation parameters are valid
- Check whether the seed value is within the allowed range
- Check whether the image URL is publicly accessible
- Check whether the base64 content is complete and valid
- Modify the parameters and retry
429 Too Many Requests
Meaning: The request rate is too high and exceeds the RPM limit of the current account. Common causes:- RPM limit exceeded
- Free users are limited to RPM 20
- Too many concurrent requests
- Too many repeated requests in a short period
- Automatic retry frequency is too high
- Wait 1 minute and try again
- Reduce the request frequency
- Control the number of concurrent requests
- Add a reasonable retry mechanism
- Avoid repeated requests within a short period
- If the request volume is high, upgrade to a Token Plan
431 Request Header Fields Too Large
Meaning: The request Header is too large for the server to process. Common causes:- Too much content is included in the Header
- Abnormal Authorization information
- Cookie or custom Header is too large
- A third-party tool automatically attaches too many Headers
- Reduce the request Header size
- Check whether the Authorization field is correct
- Remove unnecessary Cookies or custom Headers
- Reconfigure the request Headers in the third-party tool
- Retry after updating the Header
499 Client Closed Request
Meaning: The client closed the connection before the request was completed. Common causes:- The client timed out and disconnected
- The browser or tool interrupted the request
- Local network switched or disconnected
- Long-running task took too long to wait for
- Third-party tool canceled the request early
- Send the request again
- Check local network stability
- Increase the client timeout setting
- Avoid closing the page or interrupting the tool while the task is running
- Use asynchronous tasks or polling for long-running tasks
500 Internal Server Error
Meaning: The server encountered an internal error, or the request parameters triggered a service exception. Common causes:- Abnormal request parameters
- Image generation size does not meet the requirement
- Video generation size does not meet the requirement
- Context parameter is not configured in OpenClaw
- Temporary upstream service exception
- Check the request parameters
- Image generation dimensions must be multiples of 16
- Video generation dimensions must be multiples of 64
- Check the context parameter in OpenClaw settings
- Modify the parameters and retry
- If the issue persists after multiple retries, submit the error details to technical support
502 Bad Gateway
Meaning: The gateway or proxy failed to receive a valid response from the upstream service. Common causes:- Local network issue
- DNS resolution issue
- Proxy configuration issue
- Unstable network connection
- Temporary upstream service fluctuation
- Check the local network environment
- Try another network
- Change DNS settings
- Check proxy configuration
- Retry later
- If necessary, ask AI or technical staff to help inspect the local network configuration
503 Service Unavailable
Meaning: The service is temporarily unavailable, or the request failed due to third-party tool configuration issues. Common causes:- Incorrect model name
- Failed to fetch the model list
- No fallback model selected
- Routing is not enabled
- The third-party tool is actually sending requests to the wrong model
- Service is temporarily unavailable
- Check whether the model name is correct
- Fetch the model list again
- Select a fallback model
- Enable routing
- Check whether test model and backup model settings are correctly configured in the third-party tool
- Retry later
504 Gateway Timeout
Meaning: The gateway timed out while waiting for the upstream service to respond. Common causes:- Upstream model response timeout
- Image, video, or long-context task takes too long to process
- Unstable network connection
- High service load during peak hours
- Request complexity is too high
- Retry later
- Shorten the input content
- Lower image or video generation specifications
- Reduce concurrent requests
- Increase the client timeout setting appropriately
- Add retry logic for long-running tasks
520 Unknown Error
Meaning: Unknown error, usually related to network connection, gateway behavior, or temporary upstream service fluctuation. Common causes:- Network connection issue
- Temporary upstream service fluctuation
- Proxy configuration issue
- DNS configuration issue
- Gateway returned a non-standard error
- Retry the request
- Check the local network environment
- Check proxy configuration
- Check DNS configuration
- Retry later
- If the issue persists, submit the complete error message to technical support
522 Connection Timed Out
Meaning: The gateway timed out while connecting to the upstream service. Common causes:- Network connection timeout
- Gateway-to-upstream connection issue
- Local network issue
- Proxy configuration issue
- DNS configuration issue
- Retry the request
- Check the local network
- Check proxy configuration
- Change DNS settings
- Try again with another network environment
- Retry later
524 Timeout Occurred
Meaning: The connection was established, but the upstream service took too long to process the request. Common causes:- Long-context task takes too long
- Image generation task takes too long
- Video generation task takes too long
- High service load
- Request complexity is too high
- Retry later
- Reduce request complexity
- Shorten the context
- Lower generation specifications
- Reduce concurrent requests
- Use asynchronous tasks or polling for long-running tasks