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 #217 - Actions APIs : Tasks
Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.Kaizen #216 - Actions APIs : Email Notifications
Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes areKaizen #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 achievedKaizen #142: How to Navigate to Another Page in Zoho CRM using Client Script
Hello everyone! Welcome back to another exciting Kaizen post. In this post, let us see how you can you navigate to different Pages using Client Script. In this Kaizen post, Need to Navigate to different Pages Client Script ZDKs related to navigation A.Kaizen #210 - Answering your Questions | Event Management System using ZDK CLI
Hello Everyone, Welcome back to yet another post in the Kaizen Series! As you already may know, for the Kaizen #200 milestone, we asked for your feedback and many of you suggested topics for us to discuss. We have been writing on these topics over the
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
Zoho Map integration tasks have changed - you need to "Locate all instances of Zoho Map integration tasks in your Deluge scripts by searching for the v1 marker... before 16 January 2026"
The Zoho Map deluge integration task has been changed (as at 21 October 2025) to provide a more structured, JSON-like response. This change affects all three Zoho Map integration tasks (Geocode, Reverse Geocode, and Distance Between). More details canUsing files from Zoho CRM in Gemini/ChatGPT/Claude
Hi all, I’ve got subscriptions to Gemini and a few other AI tools which I use for tasks like data enrichment, email composition, etc. In our workflow, we often receive various documents from clients — such as process workflows, BRDs/requirement documentsZoho Analytics & Zoho Creator - Modified Time value
I'm trying to use the Zoho Creator system field 'modified time' in Zoho Analytics, but it's consistently showing 12 hours 'out' In Zoho Creator In Zoho Analytics Is this a constant difference that I just need to correct with a timezone change - or isZoho CRM - Option to create Follow-Up Task
When completing a Zoho CRM Task, it would be very helpful if there was an option to "Complete and Create Follow-Up Task" in the pop-up which appears. It could clone the task you are closing and then show it on the screen in edit mode, all the user wouldPortal For Different Apps
I found some older threads on this but didn't see anything very recent. I'm new to Zoho One so forgive me if my terminology is off a bit. I was hoping set up a single point of entry into Zoho One. So, many of the apps could be found in one single placeCalls undetected
Zoho Voice records indicate my last call ended at 6:00 PM. All incoming and outgoing calls occurred between 6:00 PM and 7:00 PM.Unable to Select Authenticated Domain as Sender
We’ve already authenticated our domain, but it’s still not appearing in the sender list when we try to run a campaign. Could you please check what might be causing this issue?Forever FREE Business Email with Zoho Mail
Forever FREE Business Email with Zoho Mail: is it available?Zoho Projects - Project Details on the Project Menu
Hi Project's team, I've helped may businesses setup and use Zoho Project and one thing I see time and time again is confusion on where to find the Project Details information. I would be much more intuitive if Project Details was on the menu before Dashboard.Introducing WhatsApp integration in Bigin
Greetings! In today's business landscape, messaging apps play a significant role in customer operations. Customers can engage with businesses, seek support, ask questions, receive personalized recommendations, read reviews, and even make purchases—allZia Conversation Summary: Context at a glance for every customer interaction
Hello everyone! Every customer conversation tells a story—but in CRM, that story is rarely in one place. A sales rep moving between multiple leads has to reopen long email threads, check call remarks, and revisit meeting notes just to remember what wasZoho Projects - Show Task List as dropdown field on Task records
Hi Project's Team, I noticed today that there is no field on a task record related to the task list it belongs to. A dropdown would be helpful for quickly moving tasks between lists while in a task. I know that you can go to "Other Actions" and chooseChanging the Default Search Criteria for Finding Duplicates
Hey everyone, is it possible to adjust the default search criteria for finding and merging duplicate records? Right now, CRM uses some (in my opinion nonsensical) fields as search criteria for duplicate records which do nothing except dilute the results.My followed tickets extension is not working under the All departments view
Hi. I've installed the My followed tickets extension. However, when I try to open the extension under the all departments view, I get the following message: 'Sorry, this extension is not supported in the All Departments view.' How can I solve this pTicket Time Entry to Timesheet
The title just about sums it up. I have searched here and not found anything relevant, but If I overlooked, then please set me straight. We have staff that do nothing but close tickets in desk all day long. These tickets represent their timesheet. Is there a way to have this information sync or for a tech to go into their timesheet themselves and sync it with their tickets of the same timeframe?? We waste a ton of time doing timesheets and the old "Clock in/Clock out" isnt detailed enough for us!!Calls undetected.
The call is not showing on the call log.Calls undetected
Zoho is not reading calls made.Multi-currency and Products
One of the main reasons I have gone down the Zoho route is because I need multi-currency support. However, I find that products can only be priced in the home currency, We sell to the US and UK. However, we maintain different price lists for each.Archiving Contacts
How do I archive a list of contacts, or individual contacts?Missing information data Zoho inventory
there some missing data in Zoho inventory connection. pick list stock counts bin location we have requested it via mail and the support team doesn’t gove feedback. has anyone achieve to get these info or to ask other ya lesCalendar Events Issues
Not able to view scheduled events on my calendarExtensions 101 webinar series: Build, integrate, and monetize with extensions
Attention developers! Are you ready to take your extension development skills to the next level? We're excited to bring back the Extensions 101 webinar series with an expanded lineup of Zoho products and an introduction to more platform features. LastCustom Related List Inside Zoho Books
Hello, We can create the Related list inside the zoho books by the deluge code, I am sharing the reference code Please have a look may be it will help you. //..........Get Org Details organizationID = organization.get("organization_id"); Recordid = cm_g_a_data.get("module_record_id");Where are recordings stored?
I have hosted a couple of test meeting, used the "record" button to start and stop the recording but I am unable to find where are those recordings saved? Can anybody help? ThanksZoho Desk's integration with Microsoft PowerBI delivers advanced analytics insights
Hello everyone, Gaining advanced insights through reports and dashboards is one of the critical requirements of every business. In addition to key metrics tracked in Zoho Desk, such as agent performance, SLA adherence, and ticket lifecycle, businessesCreate 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 coupleIMAP error message in Zoho mail
I cannot send emails today. Everything fine for years until today. Get a message: "You are yet to enable IMAP for your account. Please contact your administrator". Does anyone know how to correct this?Enhancements to Zoho Map integration tasks
Hello everyone, We're excited to announce enhancements to the Zoho Map integration tasks in Deluge, which will boost its performance. This post will walk you through the upcoming changes, explain why we're making them, and detail the steps you need toIMAP stopped working today
Hello! I've been a paid customer for more than 10 years, IMAP was always working fine. But today this is the error I've got on my iPhone: I've tried toggling the IMAP for my account (Mail -> Settings -> Mail accounts) off and on again, but that did notAre custom portals accessible on the Zoho learn smartphone app?
In other words, can users external to my organisation, once signed up, use the app in the same way as internal users? ThanksZoho Books/Inventory - Update Marketplace Sales Order via API
Hi everyone, Does anyone know if there is a way to update Sales Orders created from a marketplace intigration (Shopify in this case) via API? I'm trying to cover a scenario where an order is changed on the Shopify end and the changes must be reflectedConditional Layouts On Multi Select Field
How we can use Conditional Layouts On Multi Select Field field? Please help.Multiple columns in a form
I am evaluating Zoho Creator. However, I am seeing almost no layout control on a form. Just a basic 1 or 2 column format that is then imposed on the entire form. That's not going to work for many, many real world cases. We need multiple columns per line, and we need each line/section to occupy a single column or be able to span the columns. Someone please tell me that I'm missing something and the capability is actually there.Global search
Hi! I think it would be great to have a global search that would give you results from all records of a database, no only for a single field of a single form as we have now. Thanks!Any insights about API/v2? Having problem for a while.
I don't know why it is throwing a 404 error, my report name is correct. Has someone had this issue and how you fix it?Edit QR code with redirect to form
Guten morgen, wir haben ein Formular Reklamation_erstellen. Dort soll ein QR Code erstellt werden, der im Lieferschein angezeigt wird. Beim Scannen auf dem soll das jeweilige Formular zum BEARBEITEN geöffnet werden. Leider bekomme ich es nur so hin, dassGetting all the ingredients together for baking an app
Good day everyone. After reading a lot of the help docs and watching videos, I now started on my app. To prevent hours and hours wasted on going down the wrong track, I would like some clarification on the following. But first some background: I haveHelp Needed with Configuring ZC Microservice
I'm attempting to create a simple microservice, but am running into problems with scope and auth. Using Custom API Builder, here's my setup: 1. Method: GET 2. Auth: OAuth2 3. User Scope: All users 4. Response: Standard 5. Function: A function that returnsCreator Simplified #10: Predefine Form Field Values and Make Them Read-Only for Users
Hey Creators, Ready for this week's tip in the Creator Simplified series? Today, we will explore how to have read only fields in a form. Use Case: Assume a scenario where the default value for a Department field needs to be English Literature, but youZoho Mail : Email Outgoing Blocked
I suddenly received the following message yesterday. I cannot send any mail. Please resolve as soon as possible, I cannot work without sending email. Dear User, We regret to inform you that your email outgoing has been blocked and you will not be ableNext Page