API error FAQ

Updated at:

Common error messages and solutions for the Content Moderation API.

For more FAQs about API calls, see Content Moderation API.

Why do I get a "You have not opened Yundun Content Moderation Service" error when I call an API?

Cause: Content Moderation is not activated.

Solution: Go to the Content Moderation activation page and activate the service before calling the API.

Why do I get an "SDK.ServerUnreachable: Specified endpoint or uri is not valid" error when I deploy to an ECS instance, even though local tests pass?

Cause: The ECS instance does not have public network access. The Content Moderation API requires public network access.

Solution: Configure public network access for the ECS instance. Use the ping command to check the network connection to the endpoint of your environment. If the network is connected, check whether required dependencies for your programming language are missing or if you are using an outdated version of aliyun-**-sdk-core. Use the code samples in the SDK documentation. For more information, see SDK overview.

Why do I get an "SDK.ServerUnreachable : SocketTimeoutException has occurred on a socket read or accept" error when I use the Content Moderation SDK?

Cause: A network access error occurred. The Content Moderation API requires public network access.

Solution: Configure public network access for your ECS instance. Ping the corresponding endpoint to verify your network environment. If the network is connected, check whether required dependencies for your programming language are missing or if you are using an outdated version of aliyun-**-sdk-core. Use the code samples in the SDK documentation. For more information, see SDK overview.

Why do I get an "algo failed(ocridcard-modelnotexist)" error when I call an API?

Cause: The endpoint region does not support the OCR ID card model (ocridcard-model).

Solution: Select an endpoint in a region that supports this feature. For more information, see Endpoints.

Why do I get a "Your using subaccount is not authorized, please refer to the page" error when I call an API?

Cause: The RAM user is not authorized.

Solution: To call the Content Moderation API as a RAM user, first create the user and grant the required permissions. For more information, see Use a RAM user to call the Content Moderation API.

Why do I get a 401 (NOT_ALLOWED) error when I call an API?

Cause: This error typically occurs when you use an insecure URL for an image, video, or audio file.

Solution: Check whether your URL is secure. Verify that your IP address is not in one of the following private network ranges. Content Moderation requires a public IP address.

  • 10.0.0.0/8

  • 11.0.XX.XX/8

  • 100.64.0.0/10

  • 172.16.0.0/12

  • 192.168.0.0/16

  • 127.0.0.1/32

  • 33.0.XX.XX/8

Why do I get a 400 (BAD_REQUEST) error when I call an API?

Cause: Incorrect request parameters. If the error message is [task.url] is bad format, the URL is invalid.

Solution: Check that the API parameters are correct. If the error indicates an invalid URL, verify the URL. If the URL opens in a browser, check for special characters that may require URL encoding. For more information, see Common parameters.

Why do I get a 400 (service is invalid) error when I call the TextModeration API?

Cause: The Service parameter value is invalid. The API did not recognize the service name.

Solution: Set the Service parameter to one of the following valid values:

  • comment_detection: Moderates comments.

  • chat_detection: Moderates chat messages.

  • pgc_detection: Moderates professionally generated content (PGC).

  • nickname_detection: Moderates nicknames.

  • ad_compliance_detection: Checks for advertisement compliance.

If you use a valid service name but receive a 408 (commodity not activated) error, the service has not been activated. Go to the Content Moderation console to activate it. For more information, see Synchronous text scan.

Why do I get a 594 (EXPIRED) error when I call an API?

Cause: The task ID has expired. For example, when you query asynchronous image scan results, the task ID is valid for only 24 hours. Querying a task older than 24 hours returns an EXPIRED error.

Solution: After submitting an asynchronous scan task, poll for results every 30 seconds to retrieve them before the task ID expires.

Why do I get a 596 (PERMISSION_DENY) error when I call an API?

Cause: Possible reasons include an unauthorized account, an overdue payment, an unactivated service, or a disabled account. Refer to the error message for details.

Solution: Check whether the calling account is authorized and has no overdue payment. If you are using a RAM user, grant it the required permissions. If Content Moderation is not activated, go to the activation page to activate it. For more information, see Use a RAM user to call the Content Moderation API.

Why do I get an "AlgorithmTimeOut" error or incomplete text results when I use a synchronous OCR scan?

Cause: The AlgorithmTimeOut error indicates a scan timeout. OCR text recognition is time-consuming. Synchronous calls have a default timeout of 3 seconds. Images with large amounts of text are more likely to time out.

Solution: For images with large amounts of text, use the asynchronous OCR text recognition API (asynchronous scan). The system increases retries and applies additional optimizations to prevent timeouts.

Why do I get a 592 (DOWNLOAD_TIMEOUT) error when I call an API?

Cause: The content download timed out. The download time limit is 3 seconds. Ensure the content size is within API limits.

Solution: Check whether the image URL is accessible and whether the image can be downloaded within 3 seconds. CDN URLs may cause timeouts due to slow origin fetches. We recommend that you avoid CDN URLs. Cross-region access, such as requesting an Object Storage Service (OSS) object in a US region from a service in Singapore, is also likely to time out. Use an OSS address in the same region as the service.

Why do I get a "[task.dataId] is too long(>256)" error when I call the text moderation API?

Cause: The DataId exceeds 256 characters. DataId is a unique identifier for your business data. It can contain uppercase and lowercase letters, digits, underscores (_), hyphens (-), and periods (.). Example: cfd33235-71a4-468b-8137-a5ffe323a7e8.

Solution: Adjust the DataId parameter according to the API documentation. For more information, see Synchronous text scan.

Why do I get a "Status Code: 400" error related to an incorrect signature when calling an API over HTTP?

Cause: The HTTP signing mechanism is complex. Building the signing method yourself may introduce errors.

Solution: Use the Content Moderation SDKs, which handle signing automatically. If you must call the API over HTTP, review the signature mechanism first. For more information, see SDK overview and Request signature.

Why do I still get a 403 (Forbidden) error when using OSS violation detection after adding *.aliyuncs.com to the referer whitelist?

Cause: You do not have permissions to access the OSS bucket.

Solution: Only users who have activated Object Storage Service (OSS) can use OSS violation detection. Before using this feature, grant Content Moderation the required permissions to access your OSS buckets. For more information, see Authorize Content Moderation to access OSS buckets.

Why do I get a 480 (DOWNLOAD_FAILED) error when I call an API?

Cause: The content download failed. The URL may be inaccessible, or the content size or resolution exceeds the limits.

Solution: For image scanning, confirm the image URL is accessible. For video snapshots, some images in the snapshot sequence may fail to download. Check snapshot-related parameters, such as the time parameter. For video stream scanning, confirm the stream is being pushed during the scan.

Why do some URLs consistently return a 480 error when I call the synchronous video scan API?

Cause: The content download failed. The URL may be inaccessible, or the content size or resolution exceeds the limits.

Solution: For video snapshots, some images in the snapshot sequence may fail to download. Check snapshot-related parameters, such as the time parameter. If the issue persists, contact us through online service. For more information, see Video snapshots.

Why do I get a 480 (GIF_TOO_MUCH_PIXELS) error when I call the image moderation API?

Cause: The download failed. The GIF_TOO_MUCH_PIXELS error indicates that the content size or resolution exceeds the limits.

Solution: Image moderation supports images up to 20 MB, with a maximum height or width of 30,000 pixels (px) and a total resolution not exceeding 250 million pixels. Compress images that exceed these limits before submitting them for scanning. For more information, see Synchronous scan.

Why do I get a 480 (Input/output error) when I call the live video stream moderation API?

Cause: The download failed. The Input/output error message typically indicates streaming media file issues, such as an inaccessible or undownloadable URL.

Solution: For video stream scanning, confirm that the stream is being pushed and the live broadcast has not stopped. For video snapshots, some images in the snapshot sequence may fail to download. Check snapshot-related parameters, such as the time parameter.

Why do I get a 500 (GENERAL_ERROR) error when I call an API?

Cause: A temporary server-side error. The specific cause must be identified from the returned error message.

Solution: For occasional errors, retry the request. If the error persists, contact online service with the detailed error message.

Why do I get a 500 (service interrupted) error when I use the Content Moderation SDK?

Cause: A temporary server-side error. The service interrupted message may indicate an incompatibility between your SDK version and the server.

Solution: Ensure you are using the latest SDK version. If not, upgrade it. For more information, see Installation.

Why do I get a 500 (failed to convert to pcm) error when I call the audio moderation API?

Cause: A temporary server-side error. The failed to convert to pcm message may be caused by audio stream transcoding or fetching failure.

Solution: Check whether the audio stream is being pushed correctly. You can use tools like FFMPEG to test audio stream encoding and decoding. Supported protocols include HTTP, RTMP, and RTSP. For more information, see Asynchronous audio scan.

Why do I get a 586 (ALGO_FAILED) error when I call the Content Moderation API?

Cause: An algorithm service error, typically caused by a timeout due to network jitter.

Solution: For occasional errors, retry the request. If the error persists, contact online service.

Why do I get a 588 (EXCEED_QUOTA) error when I call the Content Moderation API?

Cause: The request rate exceeds the concurrency quota. Default quotas: 50 images/second for image scan, 20 streams/second for video scan, 20 streams/second for audio scan, 100 entries/second for text scan, and 10 images/second for image OCR.

Solution: Reduce your request frequency and queue content for scanning. To increase your quota, estimate your peak concurrency and contact your account manager.

Why do I get a 586 error when I call the image detection API?

Cause: An algorithm service error. If the error occurs only for specific images or videos, it may be caused by an encoding or decoding failure.

Solution: Check whether the image or video file is corrupted. You can use a codec tool to test decoding. Supported image formats include PNG, JPG, JPEG, BMP, GIF, and WEBP. For more information, see Synchronous scan.

Why do I get an "InvalidTimeStamp.Expired" error when I call the Content Moderation API?

Cause: The API call timestamp has expired. This error occurs when the client and server timestamps differ by more than 15 minutes.

Solution: Check whether your server time has changed recently or whether the client machine's time zone is configured correctly. For more information, see Common parameters.

Why does the audit feature in the console report an error after a long period of inactivity?

Cause: Your login session may have expired, causing an authorization failure.

Solution: If the error includes a RequestId, refresh your browser and log in to the console again. If the error persists, contact online service with the error message or a screenshot.

Why is no data returned when I use the Content Moderation text API SDK to scan a string that contains HTML tags?

Cause: If the string contains HTML or other code tags, a firewall may interpret it as a code injection attempt and block the request, resulting in no response.

Solution: Before sending text for scanning, filter out web code tags such as HTML or SQL characters to prevent firewall blocking. For more information, see Synchronous text scan.

Why do I get a "Specified time stamp or date value is expired" error when I call the OCR API before 09:00 or after 21:00?

Cause: The API call timestamp has expired. This error occurs when the client and server timestamps differ by more than 15 minutes.

Solution: Use the official SDKs (available for Java, Python, PHP, and other languages). If you must use HTTP, check whether the server time has changed recently or whether the client machine's time zone is configured correctly. For more information, see Common parameters.

Why do I get a 403 error when calling the image moderation API after I set the OSS referer whitelist to http://*.aliyuncs.com and grant the AliyunOSSReadOnlyAccess permission?

Cause: To moderate images or videos stored in Object Storage Service (OSS) with the Content Moderation API, you must use publicly accessible OSS URLs.

Solution: Generate a temporary, publicly accessible URL for the object and then call the Content Moderation API. OSS authorization-based access is not supported. If you cannot generate a public URL, use the OSS violation detection feature, which lets you moderate objects after granting Content Moderation permissions to access your OSS buckets. For more information, see OSS violation detection.

Why do I get a 406 error when I call the Content Moderation API?

Cause: Error code 406 indicates that the uploaded file or image exceeds the size limit, or that the software development kit (SDK) version is incompatible.

Solution:

  1. Check whether the uploaded image or file exceeds the size limit for the API that you call. Limits vary by API; review the applicable API documentation.

  2. If the file size is within the limit, check whether you use the latest SDK version. For the Java SDK, upgrade both the Core and Green packages. Content Moderation provides SDKs for Java, Python, PHP, and other languages. For more information, see SDK overview.

Why do I get the error "The API is invalid" when I call an API to manage custom text library configurations?

Cause: Configuration management APIs, such as those for custom text libraries, support only the China (Shanghai) endpoint, not the China (Beijing) endpoint. If you have not created any text libraries, the API returns no data.

Solution: Use the China (Shanghai) endpoint for management APIs. For more information, see Create a custom text library.

Why do I get a "UnicodeEncodeError" when running the Content Moderation Python SDK in a Jupyter Notebook or from the command line?

Cause: UnicodeEncodeError is an IDE-related error. Check your IDE's environment settings for the root cause.

Solution: Run the Python SDK in a mainstream IDE such as PyCharm. IDE-related issues depend on the specific environment and must be troubleshot independently.