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

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:
  1. Status Code
  2. Error Code
  3. Message
In this post, we have grouped the errors based on the status code , primarily focusing on the 4XX class of errors. 
  1. 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
  2. Errors with status code 401
    • AUTHENTICATION_FAILED
    • OAUTH_SCOPE_MISMATCH
    • INVALID_TOKEN
  3. Errors with the status code 403
    • NO_PERMISSION
    • FEATURE_NOT_SUPPORTED
  4. 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

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

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

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

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

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

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

    • Recent Topics

    • Canvas View in Zoho Recruit

      Is it possible or would it be possible to have the new 'Canvas View' in Zoho Recruit?

    • What impactful sales coaching techniques have you used to boost your team's performance?

      I'm curious about the real-world impact of sales coaching on team performance. What specific techniques or strategies have you found most effective in driving consistent improvement and growth in your sales team? Any success stories or lessons learned

    • Adding Taxes to paid consultations in Zoho Bookings

      I created a 'paid' consultation under Zoho Booking and integrated it with payment gateways for online/instant payment before a booking is done. How can I add 'taxes' to the price of consultation? I can add taxes to other Zoho apps (liks Books, Checkout,

    • Zoho Finance Suite - Customer Custom Tabs - Dynamic Link

      Hi Finance Suite team, When creating a Custom Tab for a Client Portal, there is no option to add dynamic parameters. This would be very helpful for adding Zoho Analytics dashboards which can be dynamically filtered through the URL to only show information

    • Possible to bold or indent text in the description field?

      As part of one item, I often have a detailed description that would be much easier to read if there was the ability to have a bulleted list or bold text and the like. Is this possible? My last invoicing software allowed markup in the field so, for example, an asterisk meant a bullet. I haven't been able to find any documentation related to this.  Any information would be appreciated. Thank you.

    • Formatting of Balance Sheet and Profit & Loss Reports

      The default format of the Balance Sheet and P&L Reports are based on the Account Types and then the individual accounts within the Chart of Accounts. These are then ordered alphabetically under these sub-headings and one is unable to re-order these or

    • UK MTD reports concerning turnover and cerash accounting

      Hi I am a sole trader, and I have just started with Zoho Books in order to comply with the new HMRC requirements. I use 'cash basis' - which I understand to mean that income is when the cash comes in (not the invoice date) and expenses are when they are

    • Retainer Invoice.

      Why ZOHO not have facilities to deduct partially advance payment from an invoice.

    • IMAP Server not responding.

      Trying to connect a phone via IMAP and getting "imap.zoho.com not responding." Is the server down, for maintenance or otherwise? I've tried this on two different devices and got the same error on both.

    • Share saved filters between others

      Hi, I am in charge to setup all zoho system in our company. I am preparing saved filters for everybody, but the only one can see its me. How can others see it? Thanks

    • Kanban view on Zoho CRM mobile app!

      What is Kanban? The name doesn't sound English, right? Yes, Kanban is a Japanese word which means 'Card you can see'. As per the meaning, Kanban in CRM is a type of list view in which the records will be displayed in cards and categorized under the given

    • Presenting ABM for Zoho CRM: Expand and retain your customers with precision

      Picture this scenario: You're a growing SaaS company ready to launch a powerful business suite, and are looking to gain traction and momentum. But as a business with a tight budget, you know acquiring new customers is slow, expensive, and often delivers

    • No practical examples of how survey data is analyzed

      There are no examples of analysis with analytics of zoho survey data. Only survey meta data is analyzed, such as number of completes, not actual analysis of responses, such as the % in each gender, cross-tabulations of survey responses. One strange characteristic

    • Zoho Creator as LMS and Membership Solution

      My client is interested in using Zoho One apps to deploy their membership academy offer. Zoho Creator was an option that came up in my research: Here are the components of the program/offer: 1. Membership portal - individual login credentials for each

    • Adding Chargebee as a Data Connector

      Is it possible to get Chargebee added as a Zoho Analytics data connector?

    • Webform & spam

      Hi, We set up 2 webform on our website, fowarding the content to Zoho CRM. Since it has been opened up, we are getting lot of spam message (for now about 20 a day). To lower the  amount of false new leads we added the captcha field and new enquieries are send to the Approval Leads list. However we still get some spam. Is there any "anti spam" mechanism built in Zoho CRM, or how is the best way to avoid these kind of spam ? Thanks

    • Dropbox to Workdrive

      Namaste, Trust you all are doing well. Wanted to check how this can be done with Zoho flow. I typically receive dropbox links from my clients. Is there a way where I can provide the link to Zoho flow and it downloads the files from dropbox link to a work

    • Deals by Stages Funnel not showing in correct order

      Using the Stage-Probability Mapping for the Deals module we have created a steps our deals will pass through, RFQ, Closed/Lost, Declined/No-Go, Pricing, Submitted, Negotiations, Won. However when I view the Deal By Stages Funnel it does not show in the

    • Turning off the new UI

      Tried the new 'enhanced' UI and actively dislike it. Anyone know how to revert back?

    • Confirmation prompt before a custom button action is triggered

      Have you ever created a custom button and just hoped that you/your users are prompted first to confirm the action? Well, Zoho knows this concept. For example, in blueprint, whenever we want to advance to the next state by clicking the transition, it is

    • How to create auto populate field based on custom module in Zoho CRM?

      Hello, i'm still new to Zoho CRM and work as administrator in my company. Currently, I'm configuring layout for Quotes Module. So, the idea is, I've created a read-only field in Quotes called "Spec". I want this field automatically filled with Specification

    • Rich Text For Notes in Zoho CRM

      Hello everyone, As you know, notes are essential for recording information and ensuring smooth communication across your records. With our latest update, you can now use Rich Text formatting to organize and structure your notes more efficiently. By using

    • Change Last Name to not required in Leads

      I would like to upload 500 target companies as leads but I don't yet have contact people for them. Can you enable the option for me to turn this requirement off to need a Second Name? Moderation update (10-Jun-23): As we explore potential solutions for

    • Office 365 and CRM mail integration: permission required

      Has anyone run into this weird problem? My email server is Office 365. When I try to configure Zoho CRM to use this server, a Microsoft popup window opens requesting user and password. After entering that, I get a message in the Microsoft window saying

    • Tables improvement ideas / features

      Heya, I've been using Zoho Tables for a few months now and wanted to post some features that I think will be greatly beneficial for the tool: 1. Ability to delete a record in automation or move a record in automation. - Usecase: I move a record from one

    • Deluge - Can't get phone number SalesIQ

      Hey folks, I’m building a custom plug for SalesIQ that’s supposed to register leads into Zoho CRM. The SalesIQ chat is being implemented on WhatsApp, and in my plug I’m using this line: mobile_clean = session.get("phone").get("value"); From what I understand,

    • Zoho Desk - Community

      As a regular user of Zoho Cares Community I would really love to see the publish date of articles. For example, when I look at Announcements, it would be very beneficial to see which ones were posted recently, over those which have just and a recent comment.

    • access to quartz for my customers

      Hi how can I have access to the application quartz you use for us to send you screen rocording, this feature would be immensely useful for our customers support https://quartz.zoho.com/

    • Issue with Inline Images in Email Reply via Zoho Desk API

      Hi, I am attempting to send inline images in an email reply using the Zoho Desk API, but the images are not being displayed inline for the recipient. I have followed this documentation: https://desk.zoho.com/DeskAPIDocument#Uploads https://desk.zoho.com/DeskAPIDocument#Threads#Threads_SendEmailReply

    • How to search a value stored in a subform?

      Hello, We store serial numbers in subforms but now we would like to be able to search the values to be able to easily find the record with the serial number. I saw that it's not possible to search such values through global search but is it possible to do it an other way? Thank you,

    • Field Dependency Not Working on Detail Page in Zoho Desk

      Hi Support Team, I’ve created field dependencies between two fields in Zoho Desk, and they are working correctly on the Create and Edit layouts. However, on the Detail page, the fields are not displaying according to the dependencies I’ve set — they appear

    • How do the keyword critera work?

      Hi, I'm working on automated assignment of tickets based on keywords. How does this feature work? Where does this criteria look for keywords - email address, subject, email body? Can you please clarify this as I want to avoid overlapping with criteria

    • Error: Unsupported content type: text/html;charset=UTF-8 after tryeing to get the token for n8n automation

      I am working on ZOHO Desk automation and need to get the ZOHO auth token for n8n I have created the app in ZOHO Desk API, got client id and client secret. Added all data required to get a token in n8n. After I sign in with my ZOHO credentials in ZOHO

    • Improving Collaboration Features in Zoho Portal

      Hello Zoho Community, I’ve recently started exploring Zoho services and I’m really impressed with the wide range of features. However, I feel there is still room for improvement in the collaboration area. For example, it would be really helpful if we

    • Automated Shopify Emails Not Being Delivered

      I have an ecommerce store with Shopify. I recently set up my email to be served through Zoho. Since doing this, customers are not receiving some of our automated emails from Shopify itself. Our initial email that confirms their purchase goes through but our Shipping Notification that is automatically sent out upon fulfillment is not going through. Sometimes we get a notice that it's been classified as spam, sometimes nothing. I can send/receive email via Outlook on my desktop and I can send/receive

    • I can't log in to my account on Thunderbird

      I've just had to rebuild my PC (calamitous mess from Microsoft with Win10/Win 11 'upgrade' - they confirmed I had to start with a new build). I have used Zoho mail for years via Mozilla Thunderbird, but now I've had to download the latest version of TBird,

    • Send a campaign to one recipient.

      Very often I speak to a customer and they say they didn't see my email (maybe it went in Junk, maybe they deleted it). Anyway, I just want to go into the Campaign and send it to one person. You already have a feature very close to this - when sending a Test. While developing a campaign, I can send tests to anyone. Why can't we have this AFTER  the campaign has been sent? I know, there's a caveat, and that's in the use of merge tags. Most of the time I only use FNAME, but maybe you could check if

    • Try FSM again for our business

      We already have our customers individual equipment in CRM with serial numbers, install dates, warranty length and importantly next service which is generally 2 years. a month before the service date is due we get get a report and send out service reminders.

    • Use Zoho Books to bill for work done in Zoho Desk??

      I'm trying to see if something is possible (and if yes, how). We use Zoho One to manage our business. We have a lot of clients that will put in a ticket (via portal) to have work done. Out techs will pick up the ticket, do the work, and then log the time

    • Get Cliq Meetings in my O365 calendar

      Hi, we are currently evaluating to replace the Teams Messaging and Meetings with Cliq. We currently still have all our email and calendars in O365. What i want to achieve is, to create a (ZOHO) meeting from Cliq and have this meeting added to my Outlook/O365

    • Next Page