Kaizen #25 - Zoho CRM API - Common Errors and Error Handling

Hello everyone!

Welcome back to yet another post in Kaizen!

In this post, we will discuss the most common errors that you may encounter while using Zoho CRM APIs. You can consider this post to be a concise guide that you can refer to whenever you are stuck with any error while making API calls.

All Zoho CRM V2 APIs follow REST standards, i.e, they use the HTTP request methods GET, POST, PUT, PATCH, and DELETE.

Here is a quick glance at the functionality of each request method.

GET : To retrieve data/resource from the resource server. For instance, Get Records API .
POST : To insert or upload any new resource to the server. For instance Insert Records API .
PUT : To update an existing resource . This replaces the target resource with the updated content. For instance, the Update Records API .
PATCH : To update a specific detail of the resource. This method updates the target resource with the provided content without changing the other data. For instance, the Update Specific Information of a Notification API .
DELETE : To delete a resource at a particular location. For instance, the Delete Records API .

Now, let us see the common errors that you may face while making these API calls. Every API error has three main sections:

Status Code
Error Code
Message

In this post, we have grouped the errors based on the status code , primarily focusing on the 4XX class of errors.

Errors with status code 400

INVALID_MODULE
INVALID_DATA
DUPLICATE_DATA
MANDATORY_NOT_FOUND
PATTERN_NOT_MATCHED
INVALID_REQUEST_METHOD
REQUIRED_PARAM_MISSING
LICENSE_LIMIT_EXCEEDED

Errors with status code 401

AUTHENTICATION_FAILED
OAUTH_SCOPE_MISMATCH
INVALID_TOKEN

Errors with the status code 403

NO_PERMISSION
FEATURE_NOT_SUPPORTED

Errors with status code 404

INVALID_URL_PATTERN

1. Errors with status code 400

Possible Reasons

When there is any error in the input you specified, you will get an error status code 400.

Some of the common error codes and messages under 400 are:

a. INVALID_MODULE: the module name given seems to be invalid

{

"code": "INVALID_MODULE",

"details": {},

"message": "the module name given seems to be invalid",

"status": "error"

}

APIs in which you might face this error

Metadata APIs (except Modules Metadata), Records APIs, Subform APIs, Related List APIs, Blueprint APIs, Tags APIs (except Merge Tags and Delete Tags), Notes APIs, Files and Attachments APIs, Mass Update APIs, Share APIs.

Description

The module name specified in the Request URL or in the Parameter is incorrect . You must always specify the right API name of the module in the input. To get the list of module API names, go to Setup > Developer Space > APIs > API Names . Alternatively, the value in the key " api_name " in the Modules API indicates the API name of the module.

API names of the default modules in Zoho CRM

Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Cases, Events, Calls, Solutions, Products, Vendors, Price_Books, Quotes, Sales_Orders, Purchase_Orders, Invoices, Custom, and Activities.

b. INVALID_DATA: <<varies based on API>>

{

"code": "INVALID_DATA",

"details": {

"expected_data_type": "jsonobject"

"message": "body",

"status": "error"

}

APIs in which you might face this error

Upload Organization Photo, Users APIs (except Get Users and Get Specific User), Records APIs (except Get List of Records, Get Specific Record, Get List of Deleted Records, Search Records), Subforms APIs (except Get Subforms), Related List APIs, CRM Variable APIs (except Get Variable Data, Get Specific Variable Data, Get Variable Groups), Blueprint APIs, Tags APIs (except Get Tags List and Get Record Count for a Tag), Notes APIs (except Get Notes Data), Files and Attachments APIs, Mass Update APIs, Currencies APIs (except Get Currencies Data and Get Specific Currency), Share API, Notification APIs (except Get Notification Details).

Description

You will face this error when there is an error in the input you specified . For instance,

Input specified for any field may be in an improper JSON format (as shown in the above example, the expected JSON format is JSON Object) or an invalid data type .
The unique ID of the record to be updated may be incorrect .

You can identify the case based on the value of the "message" key.

Refer to Kaizen #1 Fields in CRM to know more about the field types.

Another similar error is UNABLE_TO_PARSE_DATATYPE. This error occurs when the request body or the parameter is in the wrong format.

APIs in which you might face this error

Delete Records, Delink Related Lists, Delete Variables, Delete Notes, Get Notification Details, Disable Notification.

Example:

Request URL to delete specific Leads-

https://www.zohoapis.com/crm/v2/Leads?ids= "410405000002264040,410405000002264025"

-X DELETE

{

"code": "UNABLE_TO_PARSE_DATA_TYPE",

"details": {},

"message": "either the request body or parameters is in wrong format",

"status": "error"

}

The parameters must be passed as long integers, and not strings enclosed in quotes.

c. DUPLICATE_DATA: duplicate data

{

"data": [

{

"code": "DUPLICATE_DATA",

"details": {

"api_name": "Mobile",

"id": "4150868000001747019"

"message": "duplicate data",

"status": "error"

}

]

}

APIs in which you might face this error

Add Users, Update Users, Insert Records, Update Record, Update Specific Records, Create Variables, Update Variables, Update Specific Variables, Create Tags, Update Multiple Tags, Update Specific Tags, Add Currencies.

Description

You will face this error while making the POST or PUT API calls. When you have enabled " Do not allow duplicate values " for a field, and insert or update that field in a record with a value that already exists in another record, this error will be thrown. In other words, this error is thrown when you have specified a duplicate value to a system-defined or user-defined unique field.

The value "true" for the key "unique" in the Fields metadata API indicates that the field is marked as unique. Alternatively, you can check if a field is unique in the module builder in CRM UI. Go to setup > Customization > Modules and Fields > Choose the module > Choose layout > in the more options of the desired field > Check if Do not allow duplicate values is enabled.

d. MANDATORY_NOT_FOUND: required field not found

{

"users": [

{

"code": "MANDATORY_NOT_FOUND",

"details": {

"api_name": "role"

"message": "required field not found",

"status": "error"

}

]

}

APIs in which you might face this error

Add Users, Update Users, Insert Records, Update Record, Upsert Records, Insert Subform, Update Subform, Update Related Records, Create Variables, Update Variables, Update Blueprint, Tags APIs (except Get Tags List, Get Record Count for a Tag, Delete Tags), Create Notes, Update Notes, Mass Update Records, Enable Multicurrency , Add Currencies, Update Currencies, Share Records, Update Share Permissions, Create Bulk Read Job, Create Bulk Write Job, Notification APIs (except Get Notification Details, Disable Notifications).

Description

You will face this error when you have not specified a system-defined or user-defined mandatory field in your input.

Here is the list of system-defined mandatory fields that you need to specify while inserting records in each module.

Module	System-defined mandatory field and field type
Leads	"Last_Name" - Single Line
Contacts	"Last_Name" - Single Line
Accounts	"Account_Name" - Single Line
Deals	"Deal_Name" - Single Line "Stage" - Picklist
Tasks	"Subject" - Multi Line
Calls	"Subject" - Multi LIne "Call_Type" - Picklist "Call_Start_Time" - Date/Time "Call_Duration" - Single Line
Events	"Event_Title"- Single Line "Start_DateTime" - Date/Time "End_DateTime" - Date/Time
Products	"Product_Name" - Single Line
Quotes	"Subject"- Single Line "Product_Details" - Product Line Item
Invoices	"Subject"- Single Line "Product_Details" - Product Line Item
Campaigns	"Campaign_Name" - Single Line
Vendors	"Vendor_Name"- Single Line
Price Books	"Price_Book_Name"- Single Line "Pricing_Details"- JSON Array with "from_range", "to_range", "discount"
Cases	"Case_Origin" - Picklist "Status"- Picklist "Subject" - Single Line
Solutions	"Solution_Title"- Single Line
Purchase Orders	"Subject"- Single Line "Vendor_Name"- Lookup "Product_Details" - Product Line Item
Sales Orders	"Subject"- Single Line "Product_Details" - Product Line Item

The value "true" for the key "system-mandatory" in the Fields metadata API indicates that the field is marked as mandatory. Alternatively, you can check if a field is unique in the module builder in CRM UI. Go to setup > Customization > Modules and Fields > Choose the module > Choose layout > in the more options of the desired field > Check if Mark as required is enabled .

e. PATTERN_NO_MATCHED: Please check if the input values are correct

{

"code": "PATTERN_NOT_MATCHED",

"details": {

"api_name": "type"

"message": "Please check whether the input values are correct",

"status": "error"

}

APIs in which you might face this error

Get Users, Get List of Records, Search Records, Get List of Deleted Records, Get Shared Record Details, Add Tags to Specific Records, Add Tags to Multiple Records.

Description

All parameters can take only allowed values. You will face this error when you specify a value to a parameter other than the one(s) allowed. For instance, in Get Users API, for the type parameter, you can specify only the following values: AllUsers, ActiveUsers, DeactiveUsers, ConfirmedUsers, NotConfirmedUsers, DeletedUsers, ActiveConfirmedUsers, AdminUsers, ActiveConfirmedAdmins, CurrentUser. If you specify any other value, the above mentioned error will be thrown.

f. INVALID_REQUEST_METHOD: The http request method type is not a valid one

{

"code": "INVALID_REQUEST_METHOD",

"details": {},

"message": "The http request method type is not a valid one",

"status": "error"

}

Description

You will face this error when you use an incorrect request method . For instance, PUT instead of POST while inserting a record. Refer to the corresponding API help document to find the correct request method. You may face this error in all the available APIs .

g. REQUIRED_PARAM_MISSING: One of the expected parameter is missing

{

"code": "REQUIRED_PARAM_MISSING",

"details": {

"param": "module"

"message": "One of the expected parameter is missing",

"status": "error"

}

APIs in which you might face this error

Metadata APIs (except Module Metadata), Delete Records, Get List of Deleted Records, Search Records, Delete Variables, Tag APIs (Except Merge Tags), Delete Notes, Get Mass Update Status, Disable Notifications.

Description

You will face this error when you have not specified a mandatory parameters . Refer to the corresponding API guide for parameters tagged as mandatory .

h. LICENSE_LIMIT_EXCEEDED: Request exceeds your license limit.

{

"users": [

{

"code": "LICENSE_LIMIT_EXCEEDED",

"details": {},

"message": "Request exceeds your license limit. Need to upgrade in order to add a user",

"status": "error"

}

]

}

Description

You will face this error when you try to add user more than the maximum number of users allowed for your edition. You must upgrade your edition to add more users.

2. Errors with status code 401

Possible Reasons

You will face this error when the request lacks valid authentication for the target resource in the server.

a. AUTHENTICATION_FAILED: Authentication failed

{

"code": "AUTHENTICATION_FAILURE",

"details": {},

"message": "Authentication failed",

"status": "error"

}

Description

You will face this error when you have not used the domain-specific request URL. Refer to Kaizen #5- Environments and Domains in Zoho CRM to know more. This is a common error and you may face it while making any API call.

b. OAUTH_SCOPE_MISMATCH: invalid oauth scope to access this URL

{

"code": "OAUTH_SCOPE_MISMATCH",

"details": {},

"message": "invalid oauth scope to access this URL",

"status": "error"

}

Description

You have not specified the required scope to perform this action while generating the grant token. For instance, to retrieve users data of your organization, you must generate a token with ZohoCRM.users.READ. Refer to Kaizen #3 - Scopes in OAuth2.0 Authorization to know more about scopes.

Also, refer to scopes to get the list of available scopes in Zoho CRM. This is a common error and you may face it while making any API call.

c. INVALID_TOKEN: invalid oauth token

{

"code": "INVALID_TOKEN",

"details": {},

"message": "invalid oauth token",

"status": "error"

}

Description

You will face this error when your access token has expired. Refer to this help document to know how to refresh your access token.

To know more about errors while registering client and generating token, refer to Kaizen #4- Troubleshooting OAuth2.0. This is a common error and you may face it while making any API call.

3. Errors with status code 403

Possible Reasons

You will face this error when there is no authorization to perform an action. For instance,

The user does not have permission to perform a specific action.
The feature is not supported for your organization.

Some of the common Error Codes and Messages under 403 are:

a. NO_PERMISSION: permission denied

{

"code": "NO_PERMISSION",

"details": {

"permissions": [

"Crm_Implied_View_Leads"

]

"message": "permission denied",

"status": "error"

}

Description

The particular user does not have the permission to perform that specific action. The above error is thrown when a user who does not have permission to access the Leads module tries to retrieve Leads using Get Records API.

To update the permission to a user's profile, go to Setup > Users and Control > Security Control > Profile, and enable the necessary permissions from the list.

For the system-defined profiles like the Administrator and Standard, you will not be able to modify permissions other than basic permissions and few extension permissions. This is a common error and you may face it while making any API call.

b. FEATURE_NOT_SUPPORTED: <<varies based on feature>>

{

"code": "FEATURE_NOT_SUPPORTED",

"details": {},

"message": "The Multi-Currency feature is not available except the Enterprise and higher editions.",

"status": "error"

}

Description

You will face this error when you are trying to access a feature that is not yet enabled for your account. Refer to the corresponding API document for more details. You may face this error in the Currencies API.

4. Errors with status code 404

Possible Reasons

You will face this error when the system can communicate with the server, but the server could not find the requested resource.

a. INVALID_URL_PATTERN: Please check if the URL trying to access is a correct one

{

"code": "INVALID_URL_PATTERN",

"details": {},

"message": "Please check if the URL trying to access is a correct one",

"status": "error"

}

Description

The URL specified has syntactical errors. Refer to the specific API doc to get the correct Request URL. This is a common error and you may face it while making any API call.

We hope you found this post useful. Keep a tab on this series for more exciting topics!

Reach out to us at support@zohocrm.com if you have any questions, or let us know in the comment section.

Cheers!

Previous 'Kaizen' - CORS and the JS SDK

Next 'Kaizen' - Linking Module and Multi-Select Lookup Fields

Access your files securely from anywhere

Zoho Developer Community

New to Zoho LandingPage?

Access Zoho LandingPage

Zoho LandingPage Resources

New to Zoho Survey?

Access Zoho Survey

Latest Feature Updates

Explore our Pricing & Plans

Zoho Survey Resources

Android Mobile Surveys

Insurvey Blogs

Insight Blogs

Tips & Tricks

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Bigin?

Signup Now

Access Bigin

Latest Feature Updates

Zoho Desk Resources

Desk Community Learning Series
Digest
Functions
Meetups
Kbase
Resources
Glossary
Desk Marketplace
MVP Corner
Word of the Day

Tout forum

France ZUGs

Zoho SalesIQ Resources

Topic Participants
Sneha Sridharan

Sticky Posts
Kaizen#162 : Add Tags and Open Pre-filled Email Drafts via Client Scripts
Hello everyone! Welcome to another informative Kaizen post. In this post, let us see how to accomplish the following using Client Script. 1. How to auto-tag a record based on field update? 2. How to Open a pre-filled email draft This post will provide
Client Script | Update - Introducing Commands in Client Script!
Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands
Extension Pointers - JS SDK series #4: Managing data from a widget using ZOHO.CRM.HTTP
Handling and managing the data between two applications is a major factor for an efficient business. There are a variety of ways to handle data between Zoho CRM and other third-party applications. You can use deluge CRM tasks, create connectors, use API
Kaizen #152 - Client Script Support for the new Canvas Record Forms
Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved
Extension pointers for integrating Zoho CRM with Zoho products #8: Upload and manage Zoho Workdrive folders and files from within Zoho CRM
Keeping records on your customers and business prospects is essential for tracking data, conducting follow-ups, and running a business smoothly. When you use two separate applications, and store relevant data in each, checking and tracking data becomes