Kaizen #25 - Zoho CRM API - Common Errors and Error Handling
Hello everyone!
Welcome back to yet another post in Kaizen!
In this post, we will discuss the most common errors that you may encounter while using Zoho CRM APIs. You can consider this post to be a concise guide that you can refer to whenever you are stuck with any error while making API calls.
All Zoho CRM V2 APIs follow REST standards, i.e, they use the HTTP request methods GET, POST, PUT, PATCH, and DELETE.
Here is a quick glance at the functionality of each request method.
- GET : To retrieve data/resource from the resource server. For instance, Get Records API .
- POST : To insert or upload any new resource to the server. For instance Insert Records API .
- PUT : To update an existing resource . This replaces the target resource with the updated content. For instance, the Update Records API .
- PATCH : To update a specific detail of the resource. This method updates the target resource with the provided content without changing the other data. For instance, the Update Specific Information of a Notification API .
- DELETE : To delete a resource at a particular location. For instance, the Delete Records API .
Now, let us see the common errors that you may face while making these API calls. Every API error has three main sections:
- Status Code
- Error Code
- Message
In this post, we have grouped the errors based on the status code , primarily focusing on the 4XX class of errors.
- Errors with status code 400
- INVALID_MODULE
- INVALID_DATA
- DUPLICATE_DATA
- MANDATORY_NOT_FOUND
- PATTERN_NOT_MATCHED
- INVALID_REQUEST_METHOD
- REQUIRED_PARAM_MISSING
- LICENSE_LIMIT_EXCEEDED
- Errors with status code 401
- AUTHENTICATION_FAILED
- OAUTH_SCOPE_MISMATCH
- INVALID_TOKEN
- Errors with the status code 403
- NO_PERMISSION
- FEATURE_NOT_SUPPORTED
- Errors with status code 404
- INVALID_URL_PATTERN
1. Errors with status code 400
Possible Reasons
When there is any error in the input you specified, you will get an error status code 400.
Some of the common error codes and messages under 400 are:
a. INVALID_MODULE: the module name given seems to be invalid
{ "code": "INVALID_MODULE", "details": {}, "message": "the module name given seems to be invalid", "status": "error" } |
APIs in which you might face this error
Metadata APIs (except Modules Metadata), Records APIs, Subform APIs, Related List APIs, Blueprint APIs, Tags APIs (except Merge Tags and Delete Tags), Notes APIs, Files and Attachments APIs, Mass Update APIs, Share APIs.
Description
The module name specified in the Request URL or in the Parameter is incorrect . You must always specify the right API name of the module in the input. To get the list of module API names, go to Setup > Developer Space > APIs > API Names . Alternatively, the value in the key " api_name " in the Modules API indicates the API name of the module.
API names of the default modules in Zoho CRM
Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Cases, Events, Calls, Solutions, Products, Vendors, Price_Books, Quotes, Sales_Orders, Purchase_Orders, Invoices, Custom, and Activities.
b. INVALID_DATA: <<varies based on API>>
{ "code": "INVALID_DATA", "details": { "expected_data_type": "jsonobject" }, "message": "body", "status": "error" } |
APIs in which you might face this error
Upload Organization Photo, Users APIs (except Get Users and Get Specific User), Records APIs (except Get List of Records, Get Specific Record, Get List of Deleted Records, Search Records), Subforms APIs (except Get Subforms), Related List APIs, CRM Variable APIs (except Get Variable Data, Get Specific Variable Data, Get Variable Groups), Blueprint APIs, Tags APIs (except Get Tags List and Get Record Count for a Tag), Notes APIs (except Get Notes Data), Files and Attachments APIs, Mass Update APIs, Currencies APIs (except Get Currencies Data and Get Specific Currency), Share API, Notification APIs (except Get Notification Details).
Description
You will face this error when there is an error in the input you specified . For instance,
- Input specified for any field may be in an improper JSON format (as shown in the above example, the expected JSON format is JSON Object) or an invalid data type .
- The unique ID of the record to be updated may be incorrect .
You can identify the case based on the value of the "message" key.
Refer to Kaizen #1 Fields in CRM to know more about the field types.
Another similar error is UNABLE_TO_PARSE_DATATYPE. This error occurs when the request body or the parameter is in the wrong format.
APIs in which you might face this error
Delete Records, Delink Related Lists, Delete Variables, Delete Notes, Get Notification Details, Disable Notification.
Example:
Request URL to delete specific Leads-
-X DELETE
{ "code": "UNABLE_TO_PARSE_DATA_TYPE", "details": {}, "message": "either the request body or parameters is in wrong format", "status": "error" } |
The parameters must be passed as long integers, and not strings enclosed in quotes.
c. DUPLICATE_DATA: duplicate data
{ "data": [ { "code": "DUPLICATE_DATA", "details": { "api_name": "Mobile", "id": "4150868000001747019" }, "message": "duplicate data", "status": "error" } ] } |
APIs in which you might face this error
Add Users, Update Users, Insert Records, Update Record, Update Specific Records, Create Variables, Update Variables, Update Specific Variables, Create Tags, Update Multiple Tags, Update Specific Tags, Add Currencies.
Description
You will face this error while making the POST or PUT API calls. When you have enabled " Do not allow duplicate values " for a field, and insert or update that field in a record with a value that already exists in another record, this error will be thrown. In other words, this error is thrown when you have specified a duplicate value to a system-defined or user-defined unique field.
The value "true" for the key "unique" in the Fields metadata API indicates that the field is marked as unique. Alternatively, you can check if a field is unique in the module builder in CRM UI. Go to setup > Customization > Modules and Fields > Choose the module > Choose layout > in the more options of the desired field > Check if Do not allow duplicate values is enabled.
d. MANDATORY_NOT_FOUND: required field not found
{ "users": [ { "code": "MANDATORY_NOT_FOUND", "details": { "api_name": "role" }, "message": "required field not found", "status": "error" } ] } |
APIs in which you might face this error
Add Users, Update Users, Insert Records, Update Record, Upsert Records, Insert Subform, Update Subform, Update Related Records, Create Variables, Update Variables, Update Blueprint, Tags APIs (except Get Tags List, Get Record Count for a Tag, Delete Tags), Create Notes, Update Notes, Mass Update Records, Enable Multicurrency , Add Currencies, Update Currencies, Share Records, Update Share Permissions, Create Bulk Read Job, Create Bulk Write Job, Notification APIs (except Get Notification Details, Disable Notifications).
Description
You will face this error when you have not specified a system-defined or user-defined mandatory field in your input.
Here is the list of system-defined mandatory fields that you need to specify while inserting records in each module.
Module | System-defined mandatory field and field type |
Leads | "Last_Name" - Single Line |
Contacts | "Last_Name" - Single Line |
Accounts | "Account_Name" - Single Line |
Deals | "Deal_Name" - Single Line "Stage" - Picklist |
Tasks | "Subject" - Multi Line |
Calls | "Subject" - Multi LIne "Call_Type" - Picklist "Call_Start_Time" - Date/Time "Call_Duration" - Single Line |
Events | "Event_Title"- Single Line "Start_DateTime" - Date/Time "End_DateTime" - Date/Time |
Products | "Product_Name" - Single Line |
Quotes | "Subject"- Single Line "Product_Details" - Product Line Item |
Invoices | "Subject"- Single Line "Product_Details" - Product Line Item |
Campaigns | "Campaign_Name" - Single Line |
Vendors | "Vendor_Name"- Single Line |
Price Books | "Price_Book_Name"- Single Line "Pricing_Details"- JSON Array with "from_range", "to_range", "discount" |
Cases | "Case_Origin" - Picklist "Status"- Picklist "Subject" - Single Line |
Solutions | "Solution_Title"- Single Line |
Purchase Orders | "Subject"- Single Line "Vendor_Name"- Lookup "Product_Details" - Product Line Item |
Sales Orders | "Subject"- Single Line "Product_Details" - Product Line Item |
The value "true" for the key "system-mandatory" in the Fields metadata API indicates that the field is marked as mandatory. Alternatively, you can check if a field is unique in the module builder in CRM UI. Go to setup > Customization > Modules and Fields > Choose the module > Choose layout > in the more options of the desired field > Check if Mark as required is enabled .
e. PATTERN_NO_MATCHED: Please check if the input values are correct
{ "code": "PATTERN_NOT_MATCHED", "details": { "api_name": "type" }, "message": "Please check whether the input values are correct", "status": "error" } |
APIs in which you might face this error
Get Users, Get List of Records, Search Records, Get List of Deleted Records, Get Shared Record Details, Add Tags to Specific Records, Add Tags to Multiple Records.
Description
All parameters can take only allowed values. You will face this error when you specify a value to a parameter other than the one(s) allowed. For instance, in Get Users API, for the type parameter, you can specify only the following values: AllUsers, ActiveUsers, DeactiveUsers, ConfirmedUsers, NotConfirmedUsers, DeletedUsers, ActiveConfirmedUsers, AdminUsers, ActiveConfirmedAdmins, CurrentUser. If you specify any other value, the above mentioned error will be thrown.
f. INVALID_REQUEST_METHOD: The http request method type is not a valid one
{ "code": "INVALID_REQUEST_METHOD", "details": {}, "message": "The http request method type is not a valid one", "status": "error" } |
Description
You will face this error when you use an incorrect request method . For instance, PUT instead of POST while inserting a record. Refer to the corresponding API help document to find the correct request method. You may face this error in all the available APIs .
g. REQUIRED_PARAM_MISSING: One of the expected parameter is missing
{ "code": "REQUIRED_PARAM_MISSING", "details": { "param": "module" }, "message": "One of the expected parameter is missing", "status": "error" } |
APIs in which you might face this error
Metadata APIs (except Module Metadata), Delete Records, Get List of Deleted Records, Search Records, Delete Variables, Tag APIs (Except Merge Tags), Delete Notes, Get Mass Update Status, Disable Notifications.
Description
You will face this error when you have not specified a mandatory parameters . Refer to the corresponding API guide for parameters tagged as mandatory .
h. LICENSE_LIMIT_EXCEEDED: Request exceeds your license limit.
{ "users": [ { "code": "LICENSE_LIMIT_EXCEEDED", "details": {}, "message": "Request exceeds your license limit. Need to upgrade in order to add a user", "status": "error" } ] } |
Description
You will face this error when you try to add user more than the maximum number of users allowed for your edition. You must upgrade your edition to add more users.
2. Errors with status code 401
Possible Reasons
You will face this error when the request lacks valid authentication for the target resource in the server.
a. AUTHENTICATION_FAILED: Authentication failed
{ "code": "AUTHENTICATION_FAILURE", "details": {}, "message": "Authentication failed", "status": "error" } |
Description
You will face this error when you have not used the domain-specific request URL. Refer to Kaizen #5- Environments and Domains in Zoho CRM to know more. This is a common error and you may face it while making any API call.
b. OAUTH_SCOPE_MISMATCH: invalid oauth scope to access this URL
{ "code": "OAUTH_SCOPE_MISMATCH", "details": {}, "message": "invalid oauth scope to access this URL", "status": "error" } |
Description
You have not specified the required scope to perform this action while generating the grant token. For instance, to retrieve users data of your organization, you must generate a token with ZohoCRM.users.READ. Refer to Kaizen #3 - Scopes in OAuth2.0 Authorization to know more about scopes.
Also, refer to scopes to get the list of available scopes in Zoho CRM. This is a common error and you may face it while making any API call.
c. INVALID_TOKEN: invalid oauth token
{ "code": "INVALID_TOKEN", "details": {}, "message": "invalid oauth token", "status": "error" } |
Description
You will face this error when your access token has expired. Refer to this help document to know how to refresh your access token.
To know more about errors while registering client and generating token, refer to Kaizen #4- Troubleshooting OAuth2.0. This is a common error and you may face it while making any API call.
3. Errors with status code 403
Possible Reasons
You will face this error when there is no authorization to perform an action. For instance,
- The user does not have permission to perform a specific action.
- The feature is not supported for your organization.
Some of the common Error Codes and Messages under 403 are:
a. NO_PERMISSION: permission denied
{ "code": "NO_PERMISSION", "details": { "permissions": [ "Crm_Implied_View_Leads" ] }, "message": "permission denied", "status": "error" } |
Description
The particular user does not have the permission to perform that specific action. The above error is thrown when a user who does not have permission to access the Leads module tries to retrieve Leads using Get Records API.
To update the permission to a user's profile, go to Setup > Users and Control > Security Control > Profile, and enable the necessary permissions from the list.
For the system-defined profiles like the Administrator and Standard, you will not be able to modify permissions other than basic permissions and few extension permissions. This is a common error and you may face it while making any API call.
b. FEATURE_NOT_SUPPORTED: <<varies based on feature>>
{ "code": "FEATURE_NOT_SUPPORTED", "details": {}, "message": "The Multi-Currency feature is not available except the Enterprise and higher editions.", "status": "error" } |
Description
You will face this error when you are trying to access a feature that is not yet enabled for your account. Refer to the corresponding API document for more details. You may face this error in the Currencies API.
4. Errors with status code 404
Possible Reasons
You will face this error when the system can communicate with the server, but the server could not find the requested resource.
a. INVALID_URL_PATTERN: Please check if the URL trying to access is a correct one
{ "code": "INVALID_URL_PATTERN", "details": {}, "message": "Please check if the URL trying to access is a correct one", "status": "error" } |
Description
The URL specified has syntactical errors. Refer to the specific API doc to get the correct Request URL. This is a common error and you may face it while making any API call.
We hope you found this post useful. Keep a tab on this series for more exciting topics!
Reach out to us at support@zohocrm.com if you have any questions, or let us know in the comment section.
Cheers!
Access your files securely from anywhere
New to Zoho Recruit?
Zoho Developer Community
New to Zoho LandingPage?
Zoho LandingPage Resources
New to Zoho Survey?
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Bigin?
Topic Participants
Sneha Sridharan
Sticky Posts
Kaizen #197: Frequently Asked Questions on GraphQL APIs
🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Kaizen #198: Using Client Script for Custom Validation in Blueprint
Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Celebrating 200 posts of Kaizen! Share your ideas for the milestone post
Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQsKaizen #193: Creating different fields in Zoho CRM through API
🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Client Script | Update - Introducing Commands in Client Script!
Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands
New to Zoho TeamInbox?
Zoho TeamInbox Resources
Zoho CRM Plus Resources
Zoho Books Resources
Zoho Subscriptions Resources
Zoho Projects Resources
Zoho Sprints Resources
Qntrl Resources
Zoho Creator Resources
Zoho CRM Resources
Design. Discuss. Deliver.
Zoho Show Resources
Get Started. Write Away!
Writer is a powerful online word processor, designed for collaborative work.
Zoho CRM コンテンツ
-
オンラインヘルプ
-
Webセミナー
-
機能活用動画
-
よくある質問
-
Ebook
-
-
Zoho Campaigns
- Zoho サービスのWebセミナー
その他のサービス コンテンツ
Nederlandse Hulpbronnen
ご検討中の方
Recent Topics
unblock e-mail
please unblock my e-mails info@meatnews.gr and myrtokaterini@meatnews.grAdd Zoho Mail for users who do not need Zoho One
We have licenses for ZOho One for teams that need to use the suite of products that Zoho One offers. We have 8 more people who only need email access and we would like to add just a Zoho Mail. They do not need the Zoho One license. We are currentlyZoho Projects - Q2 Updates | 2025
Hello Users, With this year's second quarter behind us, Zoho Projects is marching towards expanding its usability with a user-centered, more collaborative, customizable, and automated attribute. But before we chart out plans for what’s next, it’s worthZML vs HTML Snippet - which is better?
Are there certain use cases where one is better than the other?Auto CheckOut Based On Shift.
This Deluge script runs on a scheduled basis to automatically set the 'Actual_Check_Out' time for employees who haven't manually checked out. If the current time is past their scheduled 'Shift_End_Time', the script updates the check-out time to matchHow to remove some users in zoho accounts
How to remove some users in Zoho accounts.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. ForInfinite loop of account verification
Hi I can't do anything on my zoho account. I always get this message Hi Sheriffo Ceesay As a security measure, you need to link your phone number with this account and verify it to proceed further. When ever I supply the details, it displays that the number is associated with another account. I don't have any other account on zoho so this is really annoying.Load PO_Date field (Purchase Order) with current date in Deluge
Hi, I'm not a full time developer, just helping to customize our CRM, in the small company I work for. There must be something wrong with me, because I can't do something so simple as complete a field with the current date in a function using Deluge.Zoho CRM in Microsoft Power Automate Custom Connector
Hi everyone, I’m building a Power Automate flow that integrates Microsoft Bookings with Zoho CRM. The goal is to automatically create a meeting (event) in Zoho CRM whenever a new appointment is booked via Microsoft Bookings. To achieve this, I createdSpell check sucks
Come on guys, it's 2024 and your spell check is completely retarded. You gotta fix it.How to include total km for multiple trips in expense report.
Whenever I create a mileage report it only shows the total dollar amount to be reimbursed. The mileage for each individual trip is included but I also need to see the total distance for all trips in a report? How do I do this?Outgoing blocked: Unusual activity detected.
I just made payment for my Zohomail Today and have been debited so i will like to be Unblocked because this is what it says (Outgoing blocked: Unusual activity detected) Thank you i await your swift responsesZoho One Login Issue - Unable to receive OTP
Hi Support Team, I am experiencing a unique login issue with Zoho One. I am attempting to log in from India using Zoho Login credentials provided by a USA-based client. Their Zoho account is hosted on a US data center. After entering the username andQuestion Regarding Managing Sale Items in Zoho Books
Good day, I was wondering about something. Right now, Zoho Books doesn’t seem to have a way to flag certain items as being on sale. For example, if I want a list of specific items to be on sale from October 1 to October 12, the user would have to exportIn the Zoho Creator Customer Payment form i Have customer field on select of the field Data want to fetch from the invoice from based on the customer name In the Customer Payment form i Have subf
In the Zoho Creator Customer Payment form i Have customer field on select of the field Data want to fetch from the invoice from based on the customer name In the Customer Payment form i Have subform update Invoice , there i have date field,Invoice numberProblem of Import Client Users From CRM and or Expense
I am premium plan user on Projects. I have about 500 customers on Expense and CRM that integrated with each other. According to at below link, I am trying to import clients from CRM, system not allowed to select any customer. If I import from Expense,Unable to see free plan option
Hello Zoho Support Team, I hope you are doing well. I am trying to sign up for Zoho Mail, but I am unable to see the option for the free plan. Could you please guide me on how I can access or activate the free plan? Thank you for your assistance.unblock my zoho mail account. outlines@zoho.com
please unblock my zoho mail account, outlines@zoho.comdomain not verified error
Hi when i try to upload a video from zoho creator widget to zoho work drive iam getting domain not verified error.I don't know what to do .In zoho api console this is my home page url https://creatorapp.zoho.com/ and this is my redirect url:www.google.com.Iamequest to Disassociate Bigin from Zoho One and Migrate to Standalone (Upgrade to Bigin Premier – 3 Seats, Annual)
Dear Zoho One Support Team, I’m writing to request your assistance to disassociate (remove) the Bigin application from our Zoho One organization while preserving all existing Bigin data. After the disconnection is successfully completed, we intend toSMTP email sending problem
Hello, I've sent emails before, but you haven't responded. Please respond. My work is being disrupted. I can't send emails via SMTP. Initially, there were no problems, but now I'm constantly receiving 550 bounce errors. I can't use the service I paidbilling
hi, I am being billed $12/year, and I can't remember why. My User ID is 691273115 Thanks for your help, --Kitty PearlHow to add receipts
How to add receiptsUnable to enable tax checkboxes
Hi Zoho Commerce Support, I'm writing to report an issue I'm having with the tax settings in my Zoho Commerce store. I've created several tax rates under Settings > Taxes, but all of them appear with the checkbox disabled. When I try to enable a checkbox,Does Zoho Learn integrate with Zoho Connect,People,Workdrive,Project,Desk?
Can we propose Zoho LEarn as a centralised Knowledge Portal tool that can get synched with the other Zoho products and serve as a central Knowledge repository?Zoho Commerce - Enable Company Name and Tax Number collection for B2B orders in Global Edition
Please enable Company Name and Tax Details option on checkout settings in Zoho Commerce Global Edition. It is still important to collect Company Name and Tax Number for B2B sales in many countries. My business is based in Ireland (in the EU) and I haveZohoSign and ZohoBooks Integration/Workflow
Hello All, We utilize ZohoSign for signatures on tax eFiles. We utilize Dynamic KBA. Additionally, we use ZohoBooks for invoicing for these services. Is there a way to accomplish the following: Send a copy of the Tax Return, Invoice and eFiles in oneManage monthly tasks with projectsf
Hi All I run a finance and operations team where we need both teams to complete monthly tasks to ensure we hit our deadlines. Can Zoho projects be used for this. There many finance focused tools but we have Zoho one so want to explore Thanks WillZoho Suite is very slow
Since today Zoho is incredibly slow over all applications! What's going on?How can I track which zoho users are actively using Zoho CRM
I have several licenses of Zoho CRM. We now need to add a new user. I could purchase a new license, but before I do, I would like to see if any of our existing users are not actively using the license assigned to them. How can I determine the activityIs anyone else having trouble saving a custom image in their email signature, or is it just me?
When I try to save the image I get an error that says "Operation Failed" I opened a support ticket two weeks ago and received a response that it would be debugged, but it still isn’t workingCombine and hide invoice lines
In quickbooks we are able to create a invoice line that combines and hides invoices lines below. eg. Brochure design $1000 (total of lines below, the client can see this line) Graphic Design $600 (hidden but entered to reporting andOption to Disable Knowledge Base Section in Feedback Widget Popup Hello Zoho Desk Team
Hello Zoho Desk Team, How are you? We are actively using Zoho Desk and would like to make more use of the Feedback Widget. One of the ways we implement it is through the popup option. At the moment, the popup always displays the Knowledge Base section,The Social Wall: August 2025
Hello everyone, As summer ends, Zoho Social is gearing up for some exciting, bigger updates lined up for the months ahead. While those are in the works, we rolled out a few handy feature updates in August to keep your social media management running smoothly.Transaction Locking with the dynamic date
Is it possible to dynamically update dates on transaction locking. We want to lock transaction x days from todayZoho Devops
We have a Zoho one account which we have integrated with an SAS educational product, sold on a subscription model, using webhooks and API calls. We make some use of custom fields and cross module lookups and relationships. We utilize CRM, Books and billingFuel up your sales with the Zoho SalesIQ + Bigin integration
Hi everyone! We’re happy to bring you the all-new Zoho SalesIQ + Bigin integration. With this, every prospect from your website instantly becomes a contact in Bigin, complete with transcripts and follow-up tasks, so you never lose a lead again. Let'sIntroducing AI-powered Assessments & Zoho's native LLM, Zia
We’ve shipped a cleaner, faster way to create assessments in Zoho Recruit. 🚀 Instead of manually building question banks or copying old templates, you can now generate ready-to-use assessments in just a few clicks, all tailored to the role you’re hiringAbility to Reset Visitor Fields During an Active Chat Flow
Hello Zoho SalesIQ Team, We hope you are doing well. We would like to propose a feature enhancement to Zoho SalesIQ regarding the management of visitor fields within Zobot flows. Use Case: Our bot asks the visitor to provide information about a 3rd personNext Page