Kaizen #25 - Zoho CRM API - Common Errors and Error Handling

Kaizen #25 - Zoho CRM API - Common Errors and Error Handling

Hello everyone!
Welcome back to yet another post in Kaizen!
In this post, we will discuss the most common errors that you may encounter while using Zoho CRM APIs. You can consider this post to be a concise guide that you can refer to whenever you are stuck with any error while making API calls. 

All Zoho CRM V2 APIs follow REST standards, i.e, they use the HTTP request methods GET, POST, PUT, PATCH, and DELETE. 

Here is a quick glance at the functionality of each request method. 
  • GET : To retrieve data/resource from the resource server. For instance, Get Records API .
  • POST : To insert or upload any new resource to the server. For instance Insert Records API .
  • PUT : To update an existing resource . This replaces the target resource with the updated content. For instance, the Update Records API .
  • PATCH : To update a specific detail of the resource. This method updates the target resource with the provided content without changing the other data. For instance, the Update Specific Information of a Notification API . 
  • DELETE : To delete a resource at a particular location. For instance, the Delete Records API . 
Now, let us see the common errors that you may face while making these API calls. Every API error has three main sections:
  1. Status Code
  2. Error Code
  3. Message
In this post, we have grouped the errors based on the status code , primarily focusing on the 4XX class of errors. 
  1. Errors with status code 400
    • INVALID_MODULE
    • INVALID_DATA
    • DUPLICATE_DATA
    • MANDATORY_NOT_FOUND
    • PATTERN_NOT_MATCHED
    • INVALID_REQUEST_METHOD
    • REQUIRED_PARAM_MISSING
    • LICENSE_LIMIT_EXCEEDED
  2. Errors with status code 401
    • AUTHENTICATION_FAILED
    • OAUTH_SCOPE_MISMATCH
    • INVALID_TOKEN
  3. Errors with the status code 403
    • NO_PERMISSION
    • FEATURE_NOT_SUPPORTED
  4. Errors with status code 404
    • INVALID_URL_PATTERN
1. Errors with status code 400

Possible Reasons
When there is any error in the input you specified, you will get an error status code 400. 
Some of the common error codes and messages under 400 are:

a. INVALID_MODULE: the module name given seems to be invalid

{
  "code": "INVALID_MODULE",
  "details": {},
  "message": "the module name given seems to be invalid",
  "status": "error"
}

APIs in which you might face this error

Description
The module name specified in the Request URL or in the Parameter is incorrect . You must always specify the right API name of the module in the input. To get the list of module API names, go to Setup > Developer Space  > APIs > API Names . Alternatively, the value in the key " api_name " in the Modules API indicates the API name of the module. 

API names of the default modules in Zoho CRM
Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Cases, Events, Calls, Solutions, Products, Vendors, Price_Books, Quotes, Sales_Orders, Purchase_Orders, Invoices, Custom, and Activities. 

b. INVALID_DATA: <<varies based on API>>
{
  "code": "INVALID_DATA",
  "details": {
      "expected_data_type": "jsonobject"
    },
  "message": "body",
  "status": "error"
}

APIs in which you might face this error
Upload Organization Photo, Users APIs (except Get Users and Get Specific User), Records APIs (except Get List of Records, Get Specific Record, Get List of Deleted Records, Search Records), Subforms APIs (except Get Subforms), Related List APIs, CRM Variable APIs (except Get Variable Data, Get Specific Variable Data, Get Variable Groups), Blueprint APIs, Tags APIs (except Get Tags List and Get Record Count for a Tag), Notes APIs (except Get Notes Data), Files and Attachments APIs, Mass Update APIs, Currencies APIs (except Get Currencies Data and Get Specific Currency), Share API, Notification APIs (except Get Notification Details).

Description
You will face this error when there is an error in the input you specified . For instance, 
  • Input specified for any field may be in an improper JSON format (as shown in the above example, the expected JSON format is JSON Object) or an invalid data type . 
  • The unique ID of the record to be updated may be incorrect . 
You can identify the case based on the value of the "message" key. 

Refer to Kaizen #1 Fields in CRM to know more about the field types. 

Another similar error is UNABLE_TO_PARSE_DATATYPE. This error occurs when the request body or the parameter is in the wrong format. 

APIs in which you might face this error

Example:
Request URL to delete specific Leads-
https://www.zohoapis.com/crm/v2/Leads?ids= "410405000002264040,410405000002264025"
-X DELETE

{
  "code": "UNABLE_TO_PARSE_DATA_TYPE",
  "details": {},
  "message": "either the request body or parameters is in wrong format",
  "status": "error"
}

The parameters must be passed as long integers, and not strings enclosed in quotes.  

c. DUPLICATE_DATA: duplicate data

{
  "data": [
      {
        "code": "DUPLICATE_DATA",
        "details": {
            "api_name": "Mobile",
            "id": "4150868000001747019"
        },
        "message": "duplicate data",
        "status": "error"
     }
  ]
}

APIs in which you might face this error

Description
You will face this error while making the POST or PUT API calls. When you have enabled " Do not allow duplicate values " for a field, and insert or update that field in a record with a value that already exists in another record, this error will be thrown. In other words, this error is thrown when you have specified a duplicate value to a system-defined or user-defined unique field.

The value "true" for the key "unique" in the Fields metadata API indicates that the field is marked as unique. Alternatively, you can check if a field is unique in the module builder in CRM UI. Go to setup > Customization > Modules and Fields > Choose the module > Choose layout > in the more options of the desired field > Check if Do not allow duplicate values is enabled. 



d. MANDATORY_NOT_FOUND: required field not found
{
    "users": [
        {
            "code": "MANDATORY_NOT_FOUND",
            "details": {
                "api_name": "role"
            },
            "message": "required field not found",
            "status": "error"
        }
    ]
}

APIs in which you might face this error

Description
You will face this error when you have not specified a system-defined or user-defined mandatory field in your input. 

Here is the list of system-defined mandatory fields that you need to specify while inserting records in each module. 

Module
System-defined mandatory field and field type
Leads
"Last_Name" - Single Line
Contacts
"Last_Name" - Single Line
Accounts
"Account_Name" - Single Line
Deals
"Deal_Name" - Single Line
"Stage" - Picklist
Tasks
"Subject" - Multi Line
Calls
"Subject" - Multi LIne
"Call_Type" - Picklist
"Call_Start_Time" - Date/Time
"Call_Duration" - Single Line
Events
"Event_Title"- Single Line
"Start_DateTime" - Date/Time
"End_DateTime" - Date/Time
Products
"Product_Name" - Single Line
Quotes
"Subject"- Single Line
"Product_Details" - Product Line Item
Invoices
"Subject"- Single Line
"Product_Details" - Product Line Item
Campaigns
"Campaign_Name" - Single Line
Vendors
"Vendor_Name"- Single Line
Price Books
"Price_Book_Name"- Single Line
"Pricing_Details"- JSON Array with "from_range", "to_range", "discount"
Cases
"Case_Origin" - Picklist
"Status"- Picklist
"Subject" - Single Line
Solutions
"Solution_Title"- Single Line
Purchase Orders
"Subject"- Single Line
"Vendor_Name"- Lookup
"Product_Details" - Product Line Item
Sales Orders
"Subject"- Single Line
"Product_Details" - Product Line Item

The value "true" for the key "system-mandatory" in the Fields metadata API indicates that the field is marked as mandatory. Alternatively, you can check if a field is unique in the module builder in CRM UI. Go to setup > Customization > Modules and Fields > Choose the module > Choose layout > in the more options of the desired field > Check if Mark as required is enabled . 



e. PATTERN_NO_MATCHED: Please check if the input values are correct
{
    "code": "PATTERN_NOT_MATCHED",
    "details": {
        "api_name": "type"
    },
    "message": "Please check whether the input values are correct",
    "status": "error"
}

APIs in which you might face this error

Description
All parameters can take only allowed values. You will face this error when you specify a value to a parameter other than the one(s) allowed. For instance, in Get Users API, for the type parameter, you can specify only the following values: AllUsers, ActiveUsers, DeactiveUsers, ConfirmedUsers, NotConfirmedUsers, DeletedUsers, ActiveConfirmedUsers, AdminUsers, ActiveConfirmedAdmins, CurrentUser. If you specify any other value, the above mentioned error will be thrown. 

f. INVALID_REQUEST_METHOD: The http request method type is not a valid one
{
    "code": "INVALID_REQUEST_METHOD",
    "details": {},
    "message": "The http request method type is not a valid one",
    "status": "error"
}

Description
You will face this error when you use an incorrect request method . For instance, PUT instead of POST while inserting a record. Refer to the corresponding API help document to find the correct request method. You may face this error in all the available APIs . 

g. REQUIRED_PARAM_MISSING: One of the expected parameter is missing
{
    "code": "REQUIRED_PARAM_MISSING",
    "details": {
        "param": "module"
    },
    "message": "One of the expected parameter is missing",
    "status": "error"
}

APIs in which you might face this error

Description
You will face this error when you have not specified a mandatory parameters . Refer to the corresponding API guide for parameters tagged as mandatory . 

h. LICENSE_LIMIT_EXCEEDED: Request exceeds your license limit.
{ 
  "users": [
        {
            "code": "LICENSE_LIMIT_EXCEEDED",
            "details": {},
            "message": "Request exceeds your license limit. Need to upgrade in order to add a user",
            "status": "error"
        }
    ]
}

Description
You will face this error when you try to add user more than the maximum number of users allowed for your edition. You must upgrade your edition to add more users.

2. Errors with status code 401 

Possible Reasons 
You will face this error when the request lacks valid authentication for the target resource in the server.

a. AUTHENTICATION_FAILED: Authentication failed 
{
    "code": "AUTHENTICATION_FAILURE",
    "details": {},
    "message": "Authentication failed",
    "status": "error"
}

Description
You will face this error when you have not used the domain-specific request URL. Refer to Kaizen #5- Environments and Domains in Zoho CRM to know more. This is a common error and you may face it while making any API call. 

b. OAUTH_SCOPE_MISMATCH: invalid oauth scope to access this URL 
{
    "code": "OAUTH_SCOPE_MISMATCH",
    "details": {},
    "message": "invalid oauth scope to access this URL",
    "status": "error"
}

Description 
You have not specified the required scope to perform this action while generating the grant token. For instance, to retrieve users data of your organization, you must generate a token with ZohoCRM.users.READ. Refer to Kaizen #3 - Scopes in OAuth2.0 Authorization to know more about scopes.

Also, refer to scopes to get the list of available scopes in Zoho CRM. This is a common error and you may face it while making any API call.

c. INVALID_TOKEN: invalid oauth token 
{
    "code": "INVALID_TOKEN",
    "details": {},
    "message": "invalid oauth token",
    "status": "error"
}

Description 
You will face this error when your access token has expired. Refer to this help document to know how to refresh your access token.

To know more about errors while registering client and generating token, refer to Kaizen #4- Troubleshooting OAuth2.0. This is a common error and you may face it while making any API call.

3. Errors with status code 403 

Possible Reasons 
You will face this error when there is no authorization to perform an action. For instance,
  • The user does not have permission to perform a specific action. 
  • The feature is not supported for your organization. 
Some of the common Error Codes and Messages under 403 are:

a. NO_PERMISSION: permission denied 
{
    "code": "NO_PERMISSION",
    "details": {
        "permissions": [
            "Crm_Implied_View_Leads"
        ]
    },
    "message": "permission denied",
    "status": "error"
}

Description 
The particular user does not have the permission to perform that specific action. The above error is thrown when a user who does not have permission to access the Leads module tries to retrieve Leads using Get Records API.

To update the permission to a user's profile, go to Setup > Users and Control > Security Control > Profile, and enable the necessary permissions from the list.

For the system-defined profiles like the Administrator and Standard, you will not be able to modify permissions other than basic permissions and few extension permissions. This is a common error and you may face it while making any API call.

b. FEATURE_NOT_SUPPORTED: <<varies based on feature>> 
{
  "code": "FEATURE_NOT_SUPPORTED",
  "details": {},
  "message": "The Multi-Currency feature is not available except the Enterprise and higher editions.",
  "status": "error"
}

Description
You will face this error when you are trying to access a feature that is not yet enabled for your account. Refer to the corresponding API document for more details. You may face this error in the Currencies API.

4. Errors with status code 404 

Possible Reasons 
You will face this error when the system can communicate with the server, but the server could not find the requested resource.

a. INVALID_URL_PATTERN: Please check if the URL trying to access is a correct one 
{
    "code": "INVALID_URL_PATTERN",
    "details": {},
    "message": "Please check if the URL trying to access is a correct one",
    "status": "error"
}

Description 
The URL specified has syntactical errors. Refer to the specific API doc to get the correct Request URL. This is a common error and you may face it while making any API call.

We hope you found this post useful. Keep a tab on this series for more exciting topics!

Reach out to us at support@zohocrm.com if you have any questions, or let us know in the comment section.

Cheers!

Previous 'Kaizen' - CORS and the JS SDK

    • Recent Topics

    • Regarding the integration of Apollo.io with Zoho crm.

      I have been seeing for the last 3 months that your Apollo.io beta version is available in Zoho Flow, and this application has not gone live yet. We requested this 2 months ago, but you guys said that 'we are working on it,' and when we search on Google

    • MTD SA in the UK

      Hello ID 20106048857 The Inland Revenue have confirmed that this tax account is registered as Cash Basis In Settings>Profile I have set ‘Report Basis’ as “Cash" However, I see on Zoho on Settings>Taxes>Income Tax that the ‘Tax Basis’ is marked ‘Accrual'

    • workflow not working in subform

      I have the following code in a subform which works perfectly when i use the form alone but when i use the form as a subform within another main form it does not work. I have read something about using row but i just cant seem to figure out what to change

    • Fetch data from another table into a form field

      I have spent the day trying to work this out so i thought i would use the forum for the first time. I have two forms in the same application and when a user selects a customer name from a drop down field and would like the customer number field in the

    • Record comment filter

      Hi - I have a calendar app that we use to track tasks. I have the calendar view set up so that the logged in user only sees the record if they are assigned to the task. BUT there are instances when someone is @ mentioned in the record when they are not

    • How to View Part Inventory and Warehouse Location When Creating a Work Order in Zoho FSM

      Hi everyone, We’re currently setting up Zoho FSM and would like to improve how our team selects parts when creating a Work Order. Right now, when we add a part or item to a Work Order, we can select it from our Zoho Inventory list but we don’t see any

    • FSM too slow today !!

      Anybody else with problem today to loading FSM (WO, AP etc.)?

    • Not able to Sign In in Zoho OneAuth in Windows 10

      I recently reset my Windows 10 system, after the reset when I downloaded the OAuth app and tried to Sign In It threw an error at me. Error: Token Fetch Error. Message: Object Reference not set to an instance of an object I have attached the screenshot

    • Mapping a custom preferred date field in the estimate with the native field in the workorder

      Hi Zoho, I created a field in the estimate : "Preferred Date 1", to give the ability to my support agent to add a preferred date while viewing the client's estimate. However, in the conversion mapping (Estimate to Workorder), I'm unable to map my custom

    • The sending IP (136.143.188.15) is listed on spamrl.com as a source of spam.

      Hi, it just two day when i am using zoho mail for my business domain, today i was sending email and found that message "The sending IP (136.143.188.15) is listed on https://spamrl.com as a source of spam" I hope to know how this will affect the delivery

    • Delegates - Access to approved reports

      We realized that delegates do not have access to reports after they are approved. Many users ask questions of their delegates about past expense reports and the delegates can't see this information. Please allow delegates see all expense report activity,

    • Split functionality - Admins need ability to do this

      Admins should be able to split an expense at any point of the process prior to approval. The split is very helpful for our account coding, but to have to go back to a user and ask them to split an invoice that they simply want paid is a bit of an in

    • Is there a way to request a password?

      We add customers info into the vaults and I wanted to see if we could do some sort of "file request" like how dropbox offers with files. It would be awesome if a customer could go to a link and input a "title, username, password, url" all securely and it then shows up in our team vault or something. Not sure if that is safe, but it's the best I can think of to be semi scalable and obviously better than sending emails. I am open to another idea, just thought this would be a great feature.  Thanks,

    • Single Task Report

      I'd like a report or a way to print to PDF the task detail page. I'd like at least the Task Information section but I'd also like to see the Activity Stream, Status Timeline and Comments. I'd like to export the record and save it as a PDF. I'd like the

    • Auto-response for closed tickets

      Hi, We sometimes have users that (presumably) search their email inbox for the last correspondence with us and just hit reply - even if it's a 6 month old ticket... - this then re-opens the 6 month old ticket because of the ticket number in the email's subject. Yes, it's easy to 'Split as new Ticket', but I'd like something automated to respond to the user saying "this ticket has already been resolved and closed, please submit a new ticket". What's the best way to achieve this? Thanks, Ed

    • How to Push Zoho Desk time logged to Zoho Projects?

      I am on the last leg of my journey of finally automating time tracking, payments, and invoicing for my minutes based contact center company - I just have one final step to solve - I need time logged in zoho desk to add time a project which is associated

    • Cannot access KB within Help Center

      Im working with my boss to customize our knowledge base, but for some reason I can see the KB tab, and see the KB categories, but I cannot access the articles within the KB. We have been troubleshooting for weeks, and we have all permissions set up, customers

    • Export to excel stored amounts as text instead of numbers or accounting

      Good Afternoon, We have a quarterly billing report that we generate from our Requests. It exports to excel. However if we need to add a formula (something as simple as a sum of the column), it doesn't read the dollar amounts because the export stores

    • why my account is private?

      when i post on zohodesk see only agent only

    • Getting ZOHO Invoice certified in Portugal?

      Hello, We are ZOHO partners in Portugal and here, all the invoice software has to be certified by the government and ZOHO Invoice still isn´t certified. Any plans? Btw, we can help on this process, since we have a client that knows how to get the software certified. Thank you.

    • 500 Internal Server Error

      I have been trying to create my first app in Creator, but have been getting the 500: Internal Server Error. When I used the Create New Application link, it gave me the error after naming the application. After logging out, and back in, the application that I created was in the list, but when I try to open it to start creating my app, it gives me the 500: Internal Server Error. Please help! Also, I tried making my named app public, but I even get the error when trying to do that.

    • Client Script | Update - Client Script Support For Portals

      Dear All! We are excited to announce the highly anticipated feature: Client Script support for Portals. We understand that many of you have been eagerly awaiting this enhancement, and we are pleased to inform you that this support is now live for all

    • Professional Plan not activated after payment

      I purchased the Professional Plan for 11 users (Subscription ID: RPEU2000980748325) on 12 September 2025, and the payment has been successfully processed. However, even after more than 24 hours, my CRM account still shows “Upgrade” and behaves like a

    • how to edit the converted lead records?

      so I can fetch the converted leads records using API (COQL), using this endpoint https://www.zohoapis.com/crm/v5/coql and using COQL filter Converted__s=true for some reasons I need to change the value from a field in a converted lead record. When I try

    • Auto Update Event Field Value on Create/Edit

      Hi there, I know this question has been posted multiple times and I've been trying many of the proposed similar scripts for a while now but nothing seems to work... what might I do wrong? The error I receive is this: Value given for the variable 'meetingId'

    • Pre-orders at Zoho Commerce

      We plan to have regular producs that are avaliable for purchase now and we plan to have products that will be avaliable in 2-4 weeks. How we can take the pre-orders for these products? We need to take the money for the product now, but the delivery will

    • Constant color of a legend value

      It would be nice if we can set a constant color/pattern to a value when creating a chart. We would often use the same value in different graph options and I always have to copy the color that we've set to a certain value from a previous graph to make

    • Zoho Pagesense really this slow??? 5s delay...

      I put the pagesense on my website (hosted by webflow and fast) and it caused a 5s delay to load. do other people face similar delays?

    • Payroll and BAS ( Australian tax report format )

      Hello , I am evaluating Zoho Books and I find the interface very intuitive and straight forward. My company is currently using Quickbooks Premier the Australian version. Before we can consider moving the service we would need to have the following addressed : 1.Payroll 2.BAS ( business activity statement ) for tax purposes 3.Some form of local backup and possible export of data to a widely accepted format. Regards Codrin Mitin

    • Problem with Email an invoice with multiple attachments using API

      I have an invoice with 3 attachments. When I send an email manually using the UI, everything works correctly. I receive an email with three attachments. The problem occurs when I try to initiate sending an email using the API. The email comes with only

    • Page Layouts for Standard Modules like CRM

      For standard modules like quotes, invoices, purchase orders, etc, it would be a great feature to be able to create custom page layouts with custom fields in Zoho Books similar to how you can in Zoho CRM. For example, and my current use case, I have a

    • Non-depreciating fixed asset

      Hi! There are non-depreciable fixed assets (e.g. land). It would be very useful to be able to create a new type of fixed asset (within the fixed assets module) with a ‘No depreciation’ depreciation method. There is always the option of recording land

    • Fixed asset management

      I want to know if there is any individual module for fixed assets management

    • One time sale item in billing automatically detects as service

      if i have some items which i don't want to add in my "item" list because its sold only for one time. but when i type item name in invoice, it (system) automatically takes it as a service and despite of HSN , it shows SAC code to be entered. if its selectable i.e. either item or service , it would be very helpful and a must have feature.

    • Project template after project creation

      How can I apply a project template AFTER the project has been created?

    • convert the project to templet

      i have some deployment ME product for different customer , i need to create a fixed template for use it rather then keeping creating this template every time

    • Related Module in Sharing Rules

      Zoho CRM team recently added the feature to filter records by Related Records It will be really beneficial if we can have this feature for Sharing Rules as well

    • Assignment Thresholds Resetting After Lead Conversion

      Hello everyone, We're facing an issue with Zoho CRM's lead assignment thresholds that makes them unsuitable for our workflow. I'm hoping to find a potential workaround or solution from the community. Here’s our current process: A new lead is created automatically

    • Zoho CRM Analytics - Allow To Reorder Dashboards

      I would like to suggest that you add the ability to reorder dashboards in the Analytics Module. I can see that this has been requested some time ago, the latest 9 years ago. I am not sure if this is a big or small endeavor, but such a small fix can go

    • Territory view for custom modules?

      I have recently activated territories however I can't seem to find how to use territories for custom modules? These modules have territories:  Contacts /  Accounts / Opportunities These modules don't have territories:   Buildings (custom module) and 

    • Next Page