Common issues with API calls-OCR(OCR)-阿里云帮助中心

This section describes common questions and answers about Alibaba Cloud OCR related to APIs and SDKs.

What are common causes of API call errors?

If an API call fails, troubleshoot as follows:

Check parameter formats. Ensure all parameters use the correct format. If you use the url parameter, make sure the URL is publicly accessible. If you use the body parameter, convert the image file to binary before sending it.
Review your API call code. See Call the OCR API to confirm that your code correctly configures AccessKeyId and AccessKeySecret, and specifies the correct endpoint.
Examine the error message. Use the returned error message to diagnose the issue further. For detailed error descriptions and recommended solutions, see Error code diagnosis.

AccessKey configuration error — If you receive the error Specified access key is not found or invalid or The specified credentials file is not exist, check whether your AccessKey and SecretKey are correctly configured, whether you are using the AccessKey pair associated with the account that activated the service (especially in cross-account scenarios), and whether the signature is correctly constructed in your code. Use the official sample code to avoid signature errors.
Invalid Type parameter — If you receive the error Specified parameter Type is not valid, verify that the Type enum value passed to RecognizeAllText or other general-purpose APIs is valid. For example, use BusinessLicense for business license recognition. For valid values, see the API documentation.
Image type mismatch — If you receive the error unmatchedImageType, the image content does not match the recognition scenario of the API. For example, sending a non-ID card image to the ID card recognition API triggers this error. Use a clear, valid image that matches the target scenario, or switch to the Qwen-OCR model on Model Studio for complex scenarios.
API whitelist restriction — Some APIs (such as flight itinerary recognition) may return a 400 error if your account has not been added to the whitelist. Follow the instructions in the documentation to apply for access.

If these steps do not resolve your issue, join the support group on DingTalk (group number: 35208328) for assistance.

Can I call the API directly over HTTP without using an SDK?

Use online debugging instead. Calling the API over HTTP requires you to manually calculate the signature and other parameters, which is complex. After successfully testing your request in the Alibaba Cloud OpenAPI OCR online debugger, download the complete project into your own codebase. The SDK already encapsulates methods for computing signatures and other common parameters, greatly simplifying development, reducing errors, and improving both efficiency and code maintainability.

On the debug page, click the SDK Examples tab to view code samples in multiple languages. Click the Run Example button to test the code online.

How do I integrate OCR services into Hermes or other agent frameworks?

Call the Qwen-OCR model API on Model Studio via HTTP. This model supports scenarios such as drawing and document text recognition, making it suitable for agent integration needs.