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 Sheets

      Hi, I am trying to transition into Zoho sheets, I have attached the issues encountered. Server issues, file trying to upload for more than 30 mins, even once uploaded my data aren't loaded. Simple calculations are not working I have attached the sample.

    • Zoho CRM + Zoho FSM : alignez vos équipes commerciales et techniques

      La vente est finalisée, mais le parcours client ne fait que commencer ! Dans les entreprises orientées service, conclure une vente représente seulement la première étape. Ce qui suit — installation, réparation ou maintenance régulière — influence grandement

    • Top Bar Shifting issue still not fixed yet

      I mentioned in a previous ticket that on Android, the top bar shifts up when you view collections or when you're in the settings. That issue still hasn't been fixed yet. I don't wanna have to reinstall the app as I've noticed for some reason, reinstalling

    • Power of Automation:: Automate the process of updating project status based on a specific task status.

      Hello Everyone, Today, I am pleased to showcase the capabilities of a custom function that is available in our Gallery. To explore the custom functions within the Gallery, please follow the steps below. Click Setup in the top right corner > Developer

    • Attention API Users: Upcoming Support for Renaming System Fields

      Hello all! We are excited to announce an upcoming enhancement in Zoho CRM: support for renaming system-defined fields! Current Behavior Currently, system-defined fields returned by the GET - Fields Metadata API have display_label and field_label properties

    • Billing Management: #3 Billing Unbilled Charges Periodically

      We had a smooth sail into Prorated Billing, a practice that ensures fairness when customers join, upgrade, or downgrade a service at any point during the billing cycle. But what happens when a customer requests additional limits or features during the

    • No bank feeds from First National Bank South Africa since 12 September

      I do not know how Zoho Books expects its customers to run a business like this. I have contacted Zoho books numerous times about this and the say it is solved - on email NO ONE ANSWERS THE SOUTH AFRICAN HELP LINE Come on Zoho Books, you cannot expect

    • Citation Problem

      I had an previous ticket (#116148702) on this subject. The basic problem is this; the "Fetch Details" feature works fine on the first attempt but fails on every subsequent attempt, Back in July after having submitted information electronically and was

    • Failing to generate Access and Refresh Token

      Hello.  I have two problems: First one when generating Access and Refresh Token I get this response:  As per the guide here : https://www.zoho.com/books/api/v3/#oauth (using server based application) I'm following all the steps. I have managed to get

    • Zeptomail 136.143.188.150 blocked by SpamCop

      Hi - it looks like this IP is being blocked, resulting in hard bounces unfortunately :( "Reason: uncategorized-bounceMessage: 5.7.1 Service unavailable; Client host [136.143.188.150] blocked using bl.spamcop.net; Blocked - see https://www.spamcop.net/bl.shtml?136.143.188.150

    • Apply transaction rules to multiple banks

      Is there any way to make transaction rules for one bank apply to other banks? It seems cumbersome to have to re-enter the same date for every account.

    • How to bulk update records with Data Enrichment by Zia

      Hi, I want to bulk update my records with Data Enrichment by Zia. How can I do this?

    • Need Guidance on SPF Flattening for Zoho Mail Configuration

      Hi everyone, I'm hoping to get some advice on optimizing my SPF record for a Zoho Mail setup. I use Zoho Mail along with several other Zoho services, and as a result, my current SPF record has grown to include multiple include mechanisms. My Cloudflare

    • How do I split a large CSV file into smaller parts for import into Zoho?

      Hi everyone, I’m trying to upload a CSV file into Zoho, but the file is very large (millions of rows), and Zoho keeps giving me errors or takes forever to process. I think the file size is too big for a single import. Manually breaking the CSV into smaller

    • Client Script Payload Size Bug

      var createParams = { "data": [{ "Name": "PS for PR 4050082000024714556", "Price_Request": { "id": "4050082000024714556" }, "Account": { "id": "4050082000021345001" }, "Deal": { "id": "4050082000023972001" }, "Owner": { "id": "4050082000007223004" }, "Approval_Status":

    • Messages not displayed from personal LinkedIn profile

      Hello. I connected both our company profile and my personal profile to Zoho social. I do see all messages from our company page but none from my private page. not even the profile is being added on top to to switch between company or private profile,

    • lead convert between modules

      Hello, The workflow we set up to automatically transfer leads registered via Zapier into the Patients module to the Leads module started to malfunction unexpectedly on September 25, 2025, at 11:00 AM. Under normal circumstances, all fields filled in the

    • Flow Task Limits - How to Monitor, Understand Consumption?

      So, I got an email last night saying that I've exhausted 70% of my tasks for this month, and encouraging me to buy more tasks. I started to dig into this, and I cannot for the life of me figure out where to find any useful information for understanding,

    • Cross References Do Not Update Correctly

      I am using cross references to reference Figures and current am just using the label and number, i.e. Figure #. As seen here: When I need to update the field, I use the update field button. But it will change the cross reference to no longer only including

    • Manage control over Microsoft Office 365 integrations with profile-based sync permissions

      Greetings all, Previously, all users in Zoho CRM had access to enable Microsoft integrations (Calendar, Contacts, and Tasks) in their accounts, regardless of their profile type. Users with administrator profiles can now manage profile-based permissions

    • How to Track and Manage Schedule Changes in Zoho Projects

      Keeping projects on track requires meticulous planning. However, unforeseen circumstances can cause changes to schedules, leading to delays. It becomes important to capture the reason for such changes to avoid them in the future. Zoho Projects acknowledges

    • Is there a notification API when a new note is addeding

      Trying to push to Cliq, or email notification when there's a new note added in module. How to implement this?

    • Collaborate Feature doesn't work

      Hello Team. It seems that the collaborate section is broken? I can post something but it all appears in "Discussions". In there is no way how I would mark something as Draft, Approval, post or any of the other filter categories? Also if I draft a post

    • Edit Permission during and after approval?

      When a record is sent for approval Can a user request for edit permission from the approver? We don't want to give edit permissions for all the records under approval Only on a case-by-case basis How can we achieve this?

    • Zoho web and mobile application not workingn

      Both zoho forms web and mobile application aren't working. I have checked my network connections and they are fine.

    • Introducing the revamped What's New page

      Hello everyone! We're happy to announce that Zoho Campaigns' What's New page has undergone a complete revamp. We've bid the old page adieu after a long time and have introduced a new, sleeker-looking page. Without further ado, let's dive into the main

    • Bulk Moving Images into Folders in the Library

      I can't seem to select multiple images to move into a folder in order to clean up my image library and organize it. Instead, I have to move each individual image into the folder and sometimes it takes MULTIPLE tries to get it to go in there. Am I missing

    • Latest updates in Zoho Meeting | Breakout rooms and End to end encryption

      Hello everyone, We’re excited to share a few updates for Zoho Meeting. Here's what we've been working on lately: Introducing Breakout Rooms for enhanced collaboration in your online meetings and End-to-end encryption to ensure that the data is encrypted

    • Systematic SPF alignment issues with Zoho subdomains

      Analysis Period: August 19 - September 1, 2025 PROBLEM SUMMARY Multiple Zoho services are causing systematic SPF authentication failures in DMARC reports from major email providers (Google, Microsoft, Zoho). While emails are successfully delivered due

    • Accidentally deleted a meeting recording -- can it be recovered?

      Hi, I accidentally deleted the recording for a meeting I had today. Is there a way I can recover it?

    • How to access email templates using Desk API?

      Trying to send an email to the customer associated to the ticket for an after hours notification and can't find the API endpoint to grab the email template. Found an example stating it should be: "https://desk.zoho.com/api/v1/emailtemplates/" + templateID;

    • Update Portal User Name using Deluge?

      Hey everyone. I have a basic intake form that gathers some general information. Our team then has a consultation with the person. If the person wants to move forward, the team pushes a CRM button that adds the user to a creator portal. That process is

    • Unable to retrieve Contact_Name field contents using Web API in javascript function

      Hello, I've added a field in the Purchase Order form to select and associate a Sales Order (Orden_de_venta, lookup field). I've also created a client script to complete some fields from the Sales Order (and the Quote), when the user specifies the related

    • Updating Woocommerce Variation Products Prices Via Zoho CRM

      I can update product prices with this flow: But I can't update variant products. I got a code from Zoho for this, but I couldn't get it to work. It needs to find the product in the CRM from the SKU field and update the variation with the price there.

    • Emails Disappearing From Inbox

      I am experiencing the unnerving problem of having some of the messages in my inbox just disappear.  It seems to happen to messages that have been in there for longer than a certain amount of time (not sure how long exactly). They are usually messages that I have flagged and know I need to act on, but have not gotten around to doing so yet.  I leave them in my inbox so I will see them and be reminded that I still need to do something about them, but at least twice now I have opened my inbox and found

    • Power of Automation :: Automatic removal of project users once the project status is changed.

      A custom function is a software code that can be used to automate a process and this allows you to automate a notification, call a webhook, or perform logic immediately after a workflow rule is triggered. This feature helps to automate complex tasks and

    • Customizing Form Questions per Recipient Group in Zoho Campaigns/Forms

      Hello everyone, I would like to ask if it’s possible in Zoho Campaigns or Zoho Forms to send out a campaign where the form questions can be customized based on the group of recipients. Use case example: I have prepared 20 questionnaire questions. For

    • Every time an event is updated, all participants receive an update email. How can I deactivate this?

      Every time an event is updated in Zoho CRM (e.g. change description, link to Lead) every participant of this meeting gets an update email. Another customer noticed this problem years ago in the Japanese community: https://help.zoho.com/portal/ja/community/topic/any-time-an-event-is-updated-on-zohocrm-calendar-it-sends-multiple-invites-to-the-participants-how-do-i-stop-that-from-happening

    • Forms - Notification When Response Submitted

      How do I set it up to generate an email notification when a response (class request) is submitted?

    • How to disable user entry on Answer Bot in Zobot

      Hi, I have an Answer Bot in my Zobot, here is the configuration: I only want the user to choose 1 of the 4 the options I have provided: When no answer found, user chooses 'I'll rephrase the question' or 'Ask a different question When answer is found,

    • Next Page