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 PDF editor has a lot of issues.

      Zoho PDF editor needs a lot of work. It hangs and glitches a lot. Deletes annotations and clearings randomly.

    • Zohom mail

      Plz resolve the problem . I hope u understand .

    • Workdrive on Android - Gallery Photo Backups

      Hello, Is there any way of backing up the photos on my android phone directly to a specific folder on Workdrive? Assuming i have the workdrive app installed on the phone in question. Emma

    • Clients not receiving emails

      I've been informed that my emails are not being received. Is there anything that I should look into to rectify this? Many thanks!

    • stock

      bom/bse : stock details or price =STOCK(C14;"price") not showing issue is #N/A! kindly resolve this problem

    • Zoho sheet desktop version

      Hi Zoho team Where can I access desktop version of zoho sheets? It is important as web version is slow and requires one to be online all the time to do even basic work. If it is available, please guide me to the same.

    • ZOHO SHEETS

      Where can I access desktop version of zoho sheets? It is important to do basic work If it is available, please guide me to the same

    • Zoho Books - France

      L’équipe de Zoho France reçoit régulièrement des questions sur la conformité de ses applications de finances (Zoho Books/ Zoho Invoice) pour le marché français. Voici quelques points pour clarifier la question : Zoho Books est un logiciel de comptabilité

    • Using Zoho Flow to create sales orders from won deal in Zoho CRM

      Hi there, We are using Zoho Flow to create sales orders automatically when a deal is won in Zoho CRM. However, the sales order requires "Product Details" to be passed in "jsonobject", and is resulting in this error: Zoho CRM says "Invalid input for invalid

    • Is Zoho Sheet available for Linux ?

      Is Zoho Sheet available for Linux ?

    • Bharat

      a

    • how to disable staff selection Zoho Booking integrated to SalesIQ?

      currently there is only one Consultant in my Zoho Bookings like this I integrate Zoho Bookings into Zoho SalesIQ to create a chatbot. Unfortunately, even though I only have one consultant for a consultation, the user have to pick the consultant. It will

    • Zoho Bookings No Sync with Outlook

      Zoho Bookings appointments are showing on my Outlook Calendar but Outlook events are not showing on Zoho Bookings. How do I fix this?

    • End Date in Zoho Bookings

      When I give my appointments a 30 minutes time I would expect the software not to even show the End Time.  But it actually makes the user pick an End Time.  Did I just miss a setting?  

    • Custom confirmation message

      How can I change the message that users see after they submit the booking form? I have to confirm some details before their appointment is officially "confirmed", so I want to change it where it doesn't say their appointment is "confirmed" but rather

    • Issue showing too many consultations in my workspace link.

      Hi Team, I’ve set up two Workspaces to track meetings from different sources. So far, this has been working well, and the two Workspaces are differentiated without any issues. However, when I navigate to Consultations and share the link to my personal

    • Deluge sendmail in Zoho Desk schedule can't send email from a verified email address

      I am trying to add a scheduled action with ZDesk using a Deluge function that sends a weekly email to specific ticket client contacts I've already verified the email address for use in ZDesk, but sendmail won't allow it in its "from:" clause. I've attached

    • Zoho Learn & Zoho Connect

      Hi, Is there a way to sync the knowledge base we have in Zoho Learn with the manuals section is Zoho Connect? Thanks,

    • Addin Support in Zoho Sheet

      Is there any addin support available in zoho sheet as like google marketplace to enhance productivity by connecting with other apps, providing AI data analysis, streamlining business processes, and more?

    • Changing Corporate Structure - How Best to Adapt Current and Future Zoho Instances

      My current company is Company A LLC with a dba ("doing business as" - essentially an alias) Product Name B. Basically, Company A is the legal entity and Product Name B is what customers see, but it's all one business right now. We currently have a Zoho

    • how to add subform over sigma in the CRM

      my new module don't have any subform available any way to add this from sigma or from the crm

    • How to Install Zoho Workdrive Desktop Sync for Ubuntu?

      Hi. I am newbie to Linux / Ubuntu. I downloaded a tar.gz file from Workdrive for installing the Workdrive Desktop Sync tool. Can someone give me step by step guide on how to install this on Ubuntu? I am using Ubuntu 19.04. Regards Senthil

    • How to upload own video?

      How can you upload your own video on your zoho website? I do not want to use another host, but i want to insert my own files. how can i do this?

    • Support new line in CRM Multiline text field display in Zoho Deluge

      Hi brainstrust, We have a Zoho CRM field which is a Muti Line (Small) field. It has data in it that has a carriage return after each line: When I pull that data in via Deluge, it displays as: I'm hoping a way I can change it from: Freehand : ENABLED Chenille

    • Announcing new features in Trident for Windows (v.1.32.5.0)

      Hello Community! Trident for Windows just got better! This update includes new features designed to improve and simplify email and calendar management—and it includes a feature you’ve been waiting for. Let’s dive into what’s new! Save emails in EML or

    • How to render either thumbnail_url or preview_url or preview_data_url

      I get 401 Unauthorised when using these urls in the <img> tag src attribute. Guide me on how to use them!

    • Zoho CRM Calendar | Custom Buttons

      I'm working with my sales team to make our scheduling process easier for our team. We primary rely on Zoho CRM calendar to organize our events for our sales team. I was wondering if there is a way to add custom button in the Calendar view on events/meeting

    • Max numbr of IMAP Accounts in Zoho Mail?

      In Zoho mail, you can manage the inboxes of other accounts using IMAP (and POP, actually) https://www.zoho.com/mail/help/external-imap-accounts.html Is there a max to the number of inboxes we can add?

    • Create Lead Button in Zoho CRM Dashboard

      Right now to create Leads in the CRM our team is going into the Lead module, selecting the "Create Lead" button, then building out the lead. Is there anyway to add the "Create Lead" button or some sort of short cut to the Zoho CRM Dashboard to cut out

    • Searching customer field

      Hello, When entering a receipt, we select customer information. The customer information is synced with Zoho CRM. However, we can't find the customer information because it searches for words that begin with the entered value. It needs to search for words

    • Introducing Version-3 APIs - Explore New APIs & Enhancements

      Happy to announce the release of Version 3 (V3) APIs with an easy to use interface, new APIs, and more examples to help you understand and access the APIs better. V3 APIs can be accessed through our new link, where you can explore our complete documentation,

    • Zoho CRM Tracking Google Enhanced Conversions

      Can anyone @Zoho, consultants, or users help me understand if Zoho CRM is going to support Google's Enhanced Conversions? I included some information from Google below about it. We use Google Adwords for our pay per click advertising for lead generation,

    • zoho click, and nord VPN

      Unfortunately, we've been having problems with Zoho Click, where essentially the line cuts off after about a minute's worth of conversation every time we are on VPN. Is there a way we can change this within the settings so it does not cut the line off

    • Connecting Portals from different Zoho apps

      Hi, I note that Zoho has functionality for customer portals for several of the Zoho apps, like CRM, Projects, Desk etc. Is there any way to connect these portals?  It would be great if we could give our customers access to a portal in which they could

    • Billing Management: #5 Usage Billing

      After understanding the nuances of Advance Billing and Retainers, we will explore one of the booming billing models. Long ago, villagers drew water from a shared well in a small village. The well was a lifeline for the entire community. Ravi, the well

    • Function #10: Update item prices automatically based on the last transaction created

      In businesses, item prices are not always fixed and can fluctuate due to various factors. If you find yourself manually adjusting the item rates every time they change, we have the ideal time-saving solution for you. In today's post, we bring you custom

    • Inventory Adjustments

      Hi, How to transfer the material from one head to another ? Like materials purchased for manufacturing the laptop need to transfer from consumption inventory (Quantity of raw materials reduced) to destination inventory ( Quantity of Laptop increased)

    • Zoho CRM Community Digest - Aug 2025 | Part 1

      Hey everyone! The first half of August went by, and we have a few announcements and some good noteworthy discussions. So, let's take a look at them! Product Updates: Introducing Connected Records feature: Zoho CRM’s Next-Gen UI now includes Connected

    • Please make it easier to Pause syncing

      right now it takes 3 clicks to get there. sounds silly, but can you make it just 2 clicks to get it done instead? thats how dropbox does it, 2 clicks to pause instead of 3.

    • How to create a Zoho CRM report with 2 child modules

      Hi all, Is it possible to create a Zoho CRM report or chart with 2 child modules? After I add the first child module, the + button only adds another parent module. It won't let me add multiple child modules at once. We don't have Zoho Analytics and would

    • Next Page