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
Can I share the drive with another Windows user?
We use the WorkDrive Sync application on a server with several remote desktop users. Our question is: Can the drive created by WorkDrive Sync be shared from one of these remote users with the other users so they can access the files, or do we need toSyncing Bills in Zoho Books to Zoho CRM
Is there any way to sync the Bills in Zoho Books in Zoho CRMAuto 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 matchERROR: Product type cannot be changed for Items having transactions.
I have mistakenly added a product type as goods for an item that was a digital service. Now when HSN/SAC became mandatory, this brought my attention to this error I did. So I tried changing the product type but it displayed this error message ProductBoost your CRM accuracy with smart Data Enrichment
Hello all! In this post let's look at data enrichment from a holistic perspective to gain more clarity on how you can use it. So, here's a quick recap of what data enrichment is and how you set it up it to enhance your existing module data! What is dataIs it possible to set a region lookup table so that my deal country can lookup this lookup table
Hi there, I would like to be able to add a data lookup table with the following fields: Country, Region. And then in my deal report, i can then lookup this table to fish out the region in my report. This will be important for my sales process to categoriseTest Emails Show Sent "via zcsend.net" in My Gmail Account
I noticed the following info... However, a few email service providers such as Outlook and Gmail will display that the email was sent by zcsend.net (Zoho campaigns’ server) on your behalf instead of just your from email address. In order to prevent this, you can go for either of these options: Do not select the check box meant for DomainKey Signature which is listed under Unverified sender domains. Include our mail servers by advanced authentication method such as SPF/ Sender ID and DomainKey/ DKIM.'UnAuthenticated Connection: zbooks_connection'
I have a zoho connection in Zoho Books, the link name es zbooks_connection, but I like to validate if exist, by example if I use this line in my code: response=zoho.books.getTemplates("", "","zbooks_connection"); But I don't have the connection I likeCalling the new 'Custom API' feature from within a Custom Widget
From what I've learned it is not possible to call an endpoint from the new "Custom API" feature within a Creator Widget. The SDK's doesn't support it yet, when calling it natively you end up with CORS issues or at least I couldn't get it working evenCannot post to Instagram. I get the error: Insufficient permission to publish on this page. Check with your page Admin to update permissions.
We had another admin that left the company. Since he left, we get this error when posting to Instagram.Zoho desk desktop application
does zoho desk has a destop applicaion?Ability to re-order Workflow Rules
We really need the ability to re-order workflow rules within departments. Either the ability to drag/drop them into a different order or something.Create an article template
I have a question concern the Knolwedge Database from Zoho Desk. There is any possibility to create an article template ? Exemple of what I research : TODAY : I want to create a lot af articles with the same baseline > I create one article > I copy/pasteChange of Blog Author
Hi, I am creating the blog post on behalf of my colleague. When I publish the post, it is showing my name as author of the post which is not intended and needs to be changed to my colleague's name. How can I change the name of the author in the blogs?? Thanks, RamananZoho FSM API Delete Record
Hi FSM Team, It would be great if you could delete a record via API. Thank you,Instant Messaging Update | Now migrate your WhatsApp Business phonenumber from another BSP to Zoho Desk | Dec'23
Hi All, Everything seems to move at lightning speed these days, and time is certainly flying by for the IM team. But we are delighted at how much ground we covered this year. 🚀 For one, we enabled WhatsApp business phone number migration so that youUpload ticket attachments via Drag-&-Drop
Hello, if you want to upload a file to the ticket attachment you need to click the button and use the file browser to select and upload the desired file. In many cases, it would be much more efficient if you could simply drag the file to the browser window...Can we disable add to cart in Zoho Commerce?
Hello, Our sales happen on the phone. During the call the customer is directed to our website to inspect the products together with the sales rep. So we need a way to present our inventory. I figured Zoho Commerce is a good fit for this use case. HoweverIntroducing 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—allZoho One account closure vs deactivation
I wonder what are the best practices and guidelines around deactivating vs deleting Zoho accounts in organisations? Any practical considerations?Schedule Zoho CRM reports only on Business Days
Hello, Is it possible to schedule reports only on business days ? We currently get daily sales reports on weekend which has no value since the sales team doesn't work on weekends. ThanksHow to install Widget in inventory module
Hi， I am trying to install a app into Sales Order Module related list, however there is no button allow me to do that. May I ask how to install widget to inventory module related list?How to track a contact or customer's past product purchases in Bigin Premiere?
Hello there. I am the sole user of Bigin for a small company (chess club), and would like to track current and past purchases made by a contact (player) or company (family which includes the player). Players may register for multiple tournaments, takeLENTITUD EN RECIBIR MAIL
Buenas tardes, Estamos experimentando lentitud en la recepción de correos electrónicos.Items should display under specific warehouse
I have configured the multi warehouse but it show all the items under all warehouse which is not correct according to our business logic, so i want that items should only display under that specific warehouse not under all the warehouses not even with zero quantity. Some items should be common but not all so is there any option for that purpose so i can specific the items to its warehouse. RegardsPartial refunds
I am trying to process refund for a one item invoice, however the refund is partial: i am getting this error while creating credit note, can anyone share some wisdom about thisBest practice importing items and matching assemblies
Hi, I was wondering what would be the best practice to import items and composite items (assemblies) From my backup, what should I import first? The items or the composite items? I am on Zoho one, using inventory and books. Kind regards, SabineBulk Fill In & Edit PO/Bill/SO/Invoice
Hello, I am adding stock in bulk on a PO, the system is automatically populating the Rate (price) and Tax from the item data. Problem is that the bill rate is different from the rate on the item data, so I have to manually erase each and enter the price.Items Below Reorder Point Report?
Is there a way to run a report of Items that are below the Reorder Point? I don't see this as a specific report, nor can I figure out how to customize any of the other stock reports to give me this information. Please tell me I'm missing something sCancelled Transfer order problem
Hello, We've canceled a transfer order, and we can't add the related items to a new Transfer Order. The system tells us that the bin doesn't have the required quantity, but when we check the item, it indicates that there are 2 units in the bin. It alsoCreating a Chart from a Report
In Zoho Analytics, is it possible to create a chart from a Pivot View report? We are looking to use Zoho Analytics to replace Excel for Sales reports and would like to be able to show both the table and the chart together.Client Portal ZOHO ONE
Dear Zoho one is fantastic option for companies but it seems to me that it is still an aggregation of aps let me explain I have zoho books with client portal so client access their invoice then I have zoho project with client portal so they can access their project but not their invoice without another URL another LOGIN Are you planning in creating a beautiful UI portal for client so we can control access to client in one location to multiple aps at least unify project and invoice aps that wouldEmail Insights included in Bigin emals are marked as SPAM everywhere
Today I noticed that email recipients who use Office 365 never receive emails sent from Bigin. Further examination showed that all Email Insights links in email headers are marked as spam/phishing by Office 365. Example screen included. The problem isData Import | Zoho Analytics Custom Query Window Size
Please increase the window size for the Custom Query Data Import. It's impossible to work with such a small query window.Name changed in settings for mailbox but still not changed when typed in To field
In the email account secretary@ i have updaetd the new staff members details but the old members name still appears when I type secretary@ in the To field. I cant work out where Zoho is finding the old name from. I have deleted the browser cache. If ICannot add my name to my domain name
I want to have My name@mydomain.com and it says my name is linked to another account already. Please fix it since I do not have another account.Establishing new Zoho email account on laptop
Good Morning: I am very long time Outlook business user and decided to try your email service last night and had established an account. I am trying to verify my account; how do I establish my Zoho email account on my laptop? I opened the account withunable to send message reason 550 5.4.6 unusual sending activity
My email account can't send message. It shows unable to send message reason 550 5.4.6 unusual sending activity detectedhow 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.Next Page