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
Centralize Knowledge. Transform Learning.
All-in-one knowledge management and training platform for your employees and customers.
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 #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.Kaizen #226: Using ZRC in Client Script
Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In thisKaizen #222 - Client Script Support for Notes Related List
Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore howKaizen #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 are
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
how to add email to existing organization i w
I am already registered my organization and i have an email id. I need one more email id but i can't find anywhere .i want the cheapest email id . how to add ?e-mail bloqueado
Estou com meu e-mail lucas@peplus.me bloqueado, preciso desbloquear para retorno de usos em minhas atividades.zoho labels api not working
We're using n8n to automte email reply using zoho api. I'm facing issue with label api. I added the required scopes but its not working. i followed zoho api documentation but didn't work. also, where do i find/how do i create zoho oauth token mentioneeedDesk DMARC forwarding failure for some senders
I am not receiving important emails into Desk, because of DMARC errors. Here's what's happening: 1. email is sent from customer e.g. john@doe.com, to my email address, e.g info@acme.com 2. email is delivered successfully to info@acme.com (a shared inboxStreams/Shared email doesn't show up in windows trident app. It works fine on MAC. Is there any difference between 2 install ?
I can see streams/share email boxs on my MAC version of trident app but i can't see them in windows version of trident app. Is there any difference between 2 install? I try to find setting but not able to see any setting to add stream/share email boxes.add zoho account
How to add a zoho mail to previous zoho account? I have twoZoho Desk Mobile App Year-End Roundup - 2025
Dear Zoho Desk users, Greetings! As you gear up for the festive season, we are excited to share a quick journey into all that is released in 2025! Zia's generative AI capabilities Zia insights can be highly beneficial in helping agents manage daily supportNarrative 17: The role of Zia AI in customer support
Behind the scenes of a successful ticketing system: BTS Series Narrative 17: The role of Zia AI in customer support Overview Zia in Zoho Desk is a layered AI assistant that combines generative AI, prediction, and automation to support agents, automateDomain Transaction
I have purchased a domain name called trainedworkforce.co.in I made the payment got the receipt but the domain is still not purchased after successful transaction .Zohomail - The "All Messages" vs "In Box"
Why do some new email message appear under the all messages view but not in my inbox? That's really annoying but to be fair I've experienced the same with gmail.error while listing mails
I can't access email in any of my folders: Oops, an error occurred - retry produces the second error response: error while listing mails (cannot parse null string). I've signed in and out of Zoho, restarted my iMac.Introducing the Zoho Projects Learning Space
Every product has its learning curve, and sometimes having a guided path makes the learning experience smoother. With that goal, we introduce a dedicated learning space for Zoho Projects, a platform where you can explore lessons, learn at your own pace,Where to show Customization Field ?
Dear Sir, I have made some New Field in Item Field Customisation. Now I don't require that field in Estimate, Sales Orders etc. I just wants that field in Sales Invoice to Show/Hide... Is that possible ?Zoho Desk 2025 round-up: Key highlights on feature releases
Hello everyone, As we gear up for 2026, here is a detailed round-up of all feature releases in Zoho Desk web throughout the year. For consolidated information on releases check out the What’s New page You can also watch these webinars. Zia in web ZiaPrint Sales Orders, Purchase Orders or Invoices from API
Hello, Is it possible to use the print option that is available in Sales Orders Purchase Orders and Invoices with the API?. I don't see any information in the docs about this. ThanksHow to show a hided report??
in CRM Report , I clicked Hide incidently , how to show the floder again? Nowhere I can find the hided report floder...Converting Customer Invoice to Purchase Bill
Hi, In my service-based business, I sometimes create the customer invoice first, and later I receive the purchase bill from the vendor for the same job. Is there any option in Zoho Books to: Convert a customer invoice into a purchase bill, or Link/associateEmail tracking inquiry
I am trying to track when my emails are opened and clicked like I previously did in HubSpot. HubSpot pretty much did the entire process automatically. After digging through, I finally found in settings --> emails --> BCC Dropbox there is an email I canMass Update of Lookup Fields not possible
Hello List I've created a custom field for Leads and Contacts 'Current Campaign'. This is very Handy as I can filter leads and then related them to a campaign. Everything ready, but then I realized that mass update doesn't work for lookup fields... aCollapsible Sections & Section Navigation Needed
The flexibility of Zoho CRM has expanded greatly in the last few years, to the point that a leads module is now permissible to contain up to 350 fields. We don't use that many, but we are using 168 fields which are broken apart into 18 different sections.Download Attached Files
Hi everyone, Brand new to Zoho Creator. I have a form with a subform. The subform has a field for "File Upload" I have this in a subform to allow multiple files to be uploaded to the parent form. Once the files are uploaded, how can i download or view them? Is this a setting I am just not seeing? If there isn't a way to download them, could i create another form field that dynamically creates the file's URL? That way a user can click the URL to get to the file? Any help with this would be greatlyTicket layout based on field or contact
Hi! I want to support the following use-case: we are delivering custom IT solutions to different accounts we have, thus our ticket layouts, fields and languages (priority, status field values should be Hungarian) will be different. How should I setupNo funcionan correctamente el calculo de las horas laborales para informe de tickets
Hola, estoy intentando sacar estadísticas de tiempo de primera respuesta y resolución en horario laboral de mis tickets, pero el calculo de horas en horario laboral no funciona correctamente cree los horarios con los feriados : Ajusté los acuerdos deZoho Mail Android app update: Set out of office response exclusively for organization members and external users, response interval
Hello everyone! We have now introduced an option to configure out of office messages exclusively for organization members and external users within the Zoho Mail app. Additionally, now you can also customize response intervals for the Out of office messages.Feature Request: Detailed View - Related Block Links!
Desperately need a view record link option on records displaying in the related blocks on a Detail View. For the love of god, please add this feature. Thank you!Sub-Form Padding in CSV Export
Hi, When you use the Sub-Form, and for example you have a Date Field on the Main Page, then Option 1 and Option 2 fields on the Subform, when you export this to CSV the Date column will only have the Date in 1 row, the first row, it would be nice to padDependent / Dynamic DropDown in ZohoSheets
Has anyone figured out a way to create a Dropdown, the values of which is dependent on Values entered in the other cell ?How do I change the order of fields in the new Task screen?
I have gone into the Task module layout, and moving the fields around does not seem to move them in the Create Task screen. Screenshot below. I have a field (Description) that we want to use frequently, but it is inconveniently placed within the MoreZoho → ShipStation Integration – Sales Order–Driven Fulfilment Workflow
Hello All, I’m reaching out to explore the best way to integrate a shipping tool into our inventory which will speed our process up. We are looking to integrate ShipStation into our existing order-to-fulfilment workflow, as we’re keen to standardise onIA ou je peux trouver comment utiliser IA
Je voudrais utiliser IA dans l'interface zoho pour m'aider quand j'ai des questions de rôle partage ou autre configuration d'automatisation, j'utiliser ChatGPT externe mais il ne connait pas toujours l'interface zoho et les réponses sont parfois longueData Processing Basis
Hi, Is there a way to automate the data processing for a candidate every time an application arrives from job boards, without requiring manual intervention? That is, to automatically acquire consent for data processing. I've seen a workflow that allowsZoho vault instal on windows
I am trying to use Zoho Vault Desktop for Windows, but I am unable to complete the sign-in process. Problem description After logging in to my Zoho account and clicking Accept on the authorization page, nothing happens. The application does not proceedZOHO GLITCHES
Ok, you guys have done a great job at building a platform that has the potential to surmount the competition but these glitches are becoming more than frustrating! This is beyond annoying, I'm trying draft lawsuits and type up privacy and refund policiesNotification to customers when I use a Zoho function
Hi all, I tried searching the community but couldn't find anything about it. I noticed that the customer receives the notification of reopening the old ticket but does not receive the notification of opening a new ticket when I use the function: "separateDate Filters in Zoho Desk Dashboard
Hello Team, Currently, in the Zoho Desk dashboard, the date filter is available only for daily, weekly, and monthly views. Could we also add a yearly date filter to allow filtering by an entire year? Additionally, in the custom date filter, it is currentlyMobile app - offline
If I made a couple of forms and my field guys had the mobile app and were somewhere without signal, could they open the app, complete and sumbit a form and have it upload when they are back in signal (we need different info at different jobs and I'm tryingZoho Survey reminder settings are extremely confusing
Hi, I just want to set 3 reminders, one week apart from the first email out. Your form is too confusing and I don't understand. Can you simplify and be more specific regarding the language used on the form ?Zobot drop down list
Hi, I am trying to create a drop down list in Zobot by creating a plug. I think I am close but I just can't get it over the line and was hoping that someone could help me. I had a little bit of help getting the script started (hence the comments) // DelugeHow to compare a subform lookup field that allows multiple entries when edited
I have a form with a subform with multiple fields. One of the fields is a lookup field that allows a multi select. On edit validation, I want a workflow to execute only when the entries in that subform field has changed. The old. function is not workingTranslation of Tooltip Messages
The descriptive help messages should be available to provide translations for.Next Page