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

    • Zoho One - Syncing Merchants and Vendors Between Zoho Expense and Zoho Books

      Hi, I'm exploring the features of Zoho One under the trial subscription and have encountered an issue with syncing Merchant information between Zoho Expense and Zoho Books. While utilizing Zoho Expense to capture receipts, I noticed that when I submit

    • Limit in number of records for subforms and multi-select lookup fields

      It is my understanding that a maximum of 100 items can be selected in a multi-select lookup field, and that a total of 200 items can be selected in total between both subforms in a given module.  Are there any ways to work around this limitation if we

    • Kaizen #136 - Zoho CRM Widgets using ReactJS

      Hey there! Welcome back to yet another insightful post in our Kaizen series! In this post, let's explore how to use ReactJS for Zoho CRM widgets. We will utilize the sample widget from one of our previous posts - Geocoding Leads' Addresses in ZOHO CRM

    • Getting Permission denied to access this portal.

      We have one user that can't login to projects even though access has been granted. This user can login to accounts.zoho.com but when login to https://projects.zoho.com/portals.do we get this error: Unauthorized login to this portal Permission denied to access this portal. Check your portal URL again. Sometimes we also get "server too busy". We have tried killing sessions (in accounts.zoho.com) and we have deleted cookies; and tried different computers and still the same problem. All others use can

    • Marketing Tip #1: Optimize item titles for SEO

      Your item title is the first thing both Google and shoppers notice. Instead of a generic “Leather Bag,” go for something detailed like “Handcrafted Leather Laptop Bag – Durable & Stylish.” This helps your items rank better in search results and instantly

    • Does Zoho Docs have a Line Number function ?

      Hi, when collaborating with coding tasks, I need an online real time share document that shows line numbers. Does Zoho's docs offer this feature ? If yes, how can I show them ? Regards, Frank

    • Setting Default Views for Custom, List and Detail Views

      Hey, Is it possible to set a default custom view, list view and detail view for a module for every user? We are onboarding a lot of non technical people that struggle with these things. Setting the views as default would really help. Btw: also setting

    • Custom function return type

      Hi, How do I create a custom deluge function in Zoho CRM that returns a string? e.g. Setup->Workflow->Custom Functions->Configure->Write own During create or edit of the function I don't see a way to change the default 'void' to anything else. Adding

    • Filter Based API request in Zoho Books using POSTMAN

      How do I GET only specified CONTACTS based on created time or modified time in Zoho Books using POSTMAN. In the api documentation, it is written we can apply filters but I need a sample request.

    • URL validation

      We use an internal intranet site which has a short DNS name which Zoho CRM will not accept.   When attempting to update the field it says "Please enter a valid URL". The URL I am trying to set is http://intranet/pm/ Our intranet is not currently setup with a full DNS name and given the amount of links using the shortname probably isn't a feasible change for us.

    • Has anyone been experiencing slow issues?

      Dear all, I just want to ask if anyone has been experiencing slow issues with Zoho Creator in the past two weeks? I worked with the ISP to improve network quality by changing routes and upgrading bandwidth, but nothing changed. I am in Vietnam.

    • Zoho Projects Roadshows 2025 - USA

      Dear Users, After an amazing response to our roadshows in 2024, we are excited to be back for the second year in a row! Join our team of experts as they walk you through the most-used features in Zoho Projects, explore powerful automation capabilities,

    • Billing Management: #6 Usage Billing in SaaS

      Imagine a customer shuffling across multiple subscriptions, a streaming service, a music app, cloud storage, and a design tool. Each one charges a flat monthly fee, regardless of how much or how little they use. Some months, the customer barely opens

    • Is there anyone who has been experiencing issues regarding the Zoho Creator Certification Website in the past 2 weeks?

      Dear all , I just wanted to ask is there anyone who was planning on taking the Zoho Creator Developer Certification Test in the past 2 weeks and have been facing errors stating that the website is under maintennance and also not allowed to access the

    • Directly Edit, Filter, and Sort Subforms on the Details Page

      Hello everyone, As you know, subforms allow you to associate multiple line items with a single record, greatly enhancing your data organization. For example, a sales order subform neatly lists all products, their quantities, amounts, and other relevant

    • GST Slabs Redefined: Stay Compliant Using Zoho Books!

      Hello Everyone! The Government of India is rolling out new GST rates, a major reform aimed at simplifying the current tax structure starting 22 September 2025. GST will move from four slabs (5%, 12%, 18%, 28%) to two main slabs (5% and 18%), plus a special

    • Allow syncing Activities from other applications

      Marketing Automation could be a much more powerful platform if you were able to sync activities into the platform (e.g. purchase, donation, etc) outside of a user doing something on your website. I'd love it if you could sync Custom CRM Modules as activities,

    • Create static subforms in Zoho CRM: streamline data entry with pre-defined values

      Last modified on (9 July, 2025): This feature was available in early access and is currently being rolled out to customers in phases. Currently available for users in the the AU, CA, and SA DCs. It will be enabled for the remaining DCs in the next couple

    • Global Sets for Multi-Select pick lists

      When is this feature coming to Zoho CRM? It would be very useful now we have got used to having it for the normal pick lists.

    • Introducing Profile Summary: Faster Candidate Insights with Zia

      We’re excited to launch Profile Summary, a powerful new feature in Zoho Recruit that transforms how you review candidate profiles. What used to take minutes of resume scanning can now be assessed in seconds—thanks to Zia. A Quick Example Say you’re hiring

    • Integración Books para cumplir la ley Crea y Crece y Ley Antifraude (VeriFactu)

      Hola: En principio, en julio de 2025, entra en vigor la ley Crea y Crece y Ley Antifraude (VeriFactu). ¿Sabéis si Zoho va a cumplir con la ley para cumplir con la facturación electrónica conectada a Hacienda? Gracias

    • Ask the Experts #1

      Hello everyone! It’s time to transform how you manage projects. Define the processes. Automate the tasks. Streamline the workflows. Let us dive into automation in Zoho Projects — from configuring workflows and custom functions to building triggers, using

    • How to overcome Zoho Deluge's time limit?

      I have built a function according to the following scheme: pages = {1,2,3,4,5,6,7,8,9,10}; for each page in pages { entriesPerPage = zoho.crm.getRecords("Accounts",page,200); for each entry in entriesPerPage { … } } Unfortunately, we have too many entries

    • Zoho Sheet - Printing - Page Breaks and Printing Customization

      I think the title is descriptive enough in that I cannot find help documentation on a simple task of adding in page brakes for separating pages on print. Thanks

    • Checking if Creator has Change History

      Like zForms - whenever an entry was updated there's an option to attached change history to email notif. Trigger -> Successful form submission

    • Zoho sites header

      Good day, Im stuck with this situation. I choose a template for my website creation. I have tweaked every instance of the visual editor, regarding the header, I have created created customize fonts presets... I have followed every single step. and my

    • Your bot just got smarter: AI-Powered routing that reads between the lines

      What if your bot could tell the difference? Between a visitor who just needs a quick answer, someone actively comparing options, and a frustrated customer one click away from leaving? Most bots can't. They deliver the same response to everyone, missing

    • 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

    • Unable to create embed code for resource of workdrive using API

      Hello Team, I am trying to create embed code for a resource using workdrive api in powershell, however facing some issues with injecting data in body. Followed Doc: https://workdrive.zoho.com/apidocs/v1/filefoldersharing/shareeveryone Please help, below

    • how to use validation rules in subform

      Is it possible to use validation rules for subforms? I tried the following code: entityMap = crmAPIRequest.toMap().get("record"); sum = 0; direct_billing = entityMap.get("direct_billing_details"); response = Map(); for each i in direct_billing { if(i.get("type")

    • Adding contact role to a specific deal js sdk malfunctioning

      i was trying to add the contact role to a specific deal contact but repeatedly i am getting this error: { "code": "SUCCESS", "details": { "statusMessage": { "code": "INVALID_DATA", "details": { "expected_data_type": "jsonobject" }, "message": "body",

    • Q3 Updates from Bigin!

      Hey Biginners, Hope you’re doing great! As we approach the end of 2025, we truly hope Bigin has been a part of helping you build your dream business this year! We've been busy working behind the scenes to bring you features that make running your business

    • New Series Announcement - Ecommerce Marketing Tips

      Running an online business is more than just having a website. It’s about getting the right customers to discover you, trust you, and keep coming back. To support your growth journey, we’re launching a weekly Marketing Tips series right here on Zoho Commerce

    • Client Script | Update - Introducing Subform Events and Actions

      Are you making the most of your subforms in Zoho CRM? Do you wish you could automate subform interactions and enhance user experience effortlessly? What if you had Client APIs and events specifically designed for subforms? We are thrilled to introduce

    • {"errors":[{"id":"500","title":"Servlet execution threw an exception"}]}

      Here's the call to move a file to trash. The resource_id is accurate and the file is present. header = Map(); header.put("Accept","application/vnd.api+json"); data = Map(); data_param1 = Map(); att_param1 = Map(); att_param1.put("status",51); data_param1.put("attributes",att_param1);

    • Converting Sales Order to Invoice via API; Problem with decimal places tax

      We are having problems converting a Sales Order to an Invoice via API Call. The cause of the issue is, that the Tax value in a Sales Order is sometimes calculated with up to 16 decimal places (e.g. 0.8730000000000001). The max decimal places allowed in

    • Zoho Canvas - Custom templates for related lists

      Hi, I see that the example pages load always one of our related lists in a custom template, but I dont know how to work with that:  1) How can i make my own custom templates for related lists?  2) Where and how can i check out existing custom templates?

    • Kaizen #147 - Frequently Asked Questions on Zoho CRM Widgets

      Heya! It's Kaizen time again, folks! This week, we aim to address common queries about Zoho CRM Widgets through frequently asked questions from our developer forum. Take a quick glance at these FAQs and learn from your peers' inquiries. 1. Where can I

    • open word file in zoho writer desktop version

      "How can I open a Microsoft Word (.doc or .docx) file in Zoho Writer if I only have the file saved on my computer and Zoho Writer doesn't appear as an option when I try 'Open with'? Is there a way to directly open the .doc file in Zoho Writer?"

    • How to invite friends on other social media platforms to one of my group chats in arattai?

      Hello, I have formed chat groups in arattai. I want to invite my friends on other social media platforms like WhatsApp/ FB to one of my groups. Different friends would be invited to different groups. How to share an invite link of one of my groups to

    • Next Page