Kaizen #203 - Answering Your Questions | Handling API Limits and Error Responses

Kaizen #203 - Answering Your Questions | Handling API Limits and Error Responses



Hi Everyone,
Welcome back to yet another post in the Kaizen Series! 
We appreciate your keen participation in the 200th milestone celebration of the Kaizen series. We will continue to answer the queries we received through the feedback. 
When working with Zoho CRM APIs, you must respect API limits, handle errors properly, and deliver meaningful experiences—even when things go wrong. In this post, we will discuss handling API limits and error responses.

Understanding Zoho CRM API Limits

Zoho CRM enforces API limits based on the purchased user licenses and add-on credits, and this is to ensure availability to all users and prevent abuse of its APIs. The following limits are applicable to Zoho CRM REST APIs.

  • API Credits Limits: Each edition (Free, Standard, Professional, etc.) comes with a set number of API credits per rolling 24-hour window. For example, Enterprise/Zoho One offers a baseline of 50,000 plus 1,000 per user license, with a cap up to 5,000,000 credits including add-one credits. You can refer to our help documentation on API limits for more details.
  • Concurrency Limits: Concurrency is the number of parallel API calls that are active at one time instance. Apps are capped at concurrent requests based on CRM edition: Free (5), Standard (10), Professional (15), Enterprise (20), Ultimate (25).
  • Sub-Concurrency Limits: Some resource-intensive APIs have their own concurrency limits (typically 10 concurrent requests): bulk updates, queries, lead conversion, mail, etc. Exceeding these returns a TOO_MANY_REQUESTS error.
  • Limits per Call: Different APIs have specific limits for the number of resources that can be inserted/updated. For example for insert, update, or upsert records, you can pass up to 100 records in one API call. Refer to the individual help documentation for any such limits.

Tips:

  • Monitor Usage: Use Zoho’s dashboard to track API credits in real time. Set alerts if you are approaching limits. Alternatively, keep an eye on the header X-API-CREDITS-REMAINING which denotes the remaining credits that will be present in the response when your API usage exceeds 50 percent or the daily available credit limit. Also, you can customize your usage notification to receive an email alert.
  • Batch Operations: Prefer bulk inserts/updates (up to 100 records/call) to reduce wasteful requests. Use composite APIs when multiple APIs need to be executed. 
  • Space Out Calls: When integrating, use logical intervals and avoid call bursts to prevent concurrency /subconcurrency limit getting applied. We have covered this in more detail in our previous Kaizen post : How to effectively handle API calls to optimize API credits?

Limits in Zoho CRM GraphQL APIs

Like our REST APIs, our GraphQL API calls also consume credits based on the type and number of resources queried. Maximum allowed credits per call is 10 credits.
Complexity for each query is calculated based on the type and number of resources requested, and maximum allowed complexity is 1,000 per query. 
Depth refers to the number of nesting layers of a field. Depth up to seven for metadata and three for records is allowed.
You can refer to our GraphQL API documentation on Credits, Complexity, and Depth for more details.

Handling Errors

 Zoho CRM REST APIs return 200 status codes for every successful API call. Each API error has these sections:
  • Status Code 
  • Error Code 
  • Message 
Different sections of an error response
Here "resource_path_index": 0 in the response indicates which segment of the URL path contains the error, counting after the API version.

Common Errors

  • 400 Bad Request:  
    • INVALID_MODULE
      • Cause: Incorrect module name (e.g., "Lead" vs "Leads").
      • Fix: Use exact API names from Setup > Developer Space > APIs.
    • INVALID_DATA
      • Cause: Malformed JSON/wrong data type.
      • Fix: Validate field formats.
    • DUPLICATE_DATA
      • Cause: Unique field value exists elsewhere.
      • Fix: Disable "Do not allow duplicates" or change value.
    • MANDATORY_NOT_FOUND
      • Cause: Missing required field (e.g., Last_Name in Contacts while trying to insert a new record in Contacts module).
      • Fix: Include all mandatory fields in the request.
  •  401 Unauthorized: 
    • AUTHENTICATION_FAILED
      • Cause: Wrong domain URL .
      • Fix: Use the correct domain-specific URL.
    • INVALID_TOKEN:
      • Cause: Expired OAuth token is used for making API call.
      • Fix: Refresh access token using the refresh token.
  • 403 Forbidden: 
    • NO_PERMISSION
      • Cause: User lacks permission for the resource.
      • Fix: Obtain necessary permission to access the resource.
  •  404 Not Found: 
    • INVALID_URL_PATTERN
      • Cause: URL syntax error.
      • Fix: Verify endpoint structure in API docs.
  •  429 Too Many Requests: 
    • TOO_MANY_REQUESTS
      • Cause: Number of API requests for the 24 hour period is exceeded or the concurrency/sub-concurrency limit of the user for the app is exceeded.
      • Fix: Make calls in accordance with the limits.
  • 207 Multi-Status: 
    • In some cases when the API is partially successful, 207 status code is returned.

Tips

  • Mandatory Fields: Provide all mandatory fields in the response body.
  • OAuth Issues: Ensure correct scopes.
  • Inspect Every Response Body: Parse responses even if the HTTP status code returned is 2XX. 
  • Validate Data Before Calling: Ensure your request matches the expected format. Clean data before submission to prevent 400-range errors (e.g., MANDATORY_NOT_FOUND, DUPLICATE_DATA).
  • Token Issues: Respond to INVALID_TOKEN with a token refresh workflow.

Error Status Code in GraphQL APIs 

Zoho CRM GraphQL APIs return errors in 200 and 400 status codes depending on error type. 200 HTTP status codes are returned in two cases. 
(a) Issue in the input when validated against the schema .
(b) Runtime errors due to credits, depth, and so on.

Refer to the Status Codes and Responses page in GraphQL for more information.
We hope you found this post useful. We will be back next week to answer another query we received.
Let us know if you have any questions in the comments or drop us an email at support@zohocrm.com.

    • 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 are

    • Kaizen #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 achieved

    • Kaizen #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

      • Recent Topics

      • Gmail is ramping up its email sender policy as of November 2025

        Hello marketers, As you may be aware, Gmail introduced a guideline for bulk senders starting February 2024. If not, here's a quick refresher straight from Google: After this policy was announced first in 2023 and soft-implemented in February 2024, we

      • Modifying iframe data of Zoho booking iframe

        Hello, I have integrated a Zoho Bookings embedded iframe into my website. Currently, I am pre-filling the booking form with default values as part of our process flow. However, I want to ensure that if an input field is already populated with a default

      • Zoho CRM Workflow and Function Backup Options

        Hi everyone! I have been able to make several backups of my CRM data and noticed that the Workflows and Functions are not included in these backups. To my knowledge, there is no backup feature for workflows and functions, which is problematic in of itself.

      • Enhance Sign CRM integration

        Hello all, I'm working on a custom Deluge script to enhance the integration between Zoho CRM and Sign by using a writer merge template for additional flexibility. I want to replicate the post-sign document integration that exists between CRM and Sign

      • YouTube Live streaming? how to? Zoom has this feature, built-in. Can't find it on zoho meetings.

        YouTube Live streaming? how to? Zoom has this feature, built-in. Can't find it on zoho meetings.

      • Is or will be possible to associate meeting transcription and summary, made by Zia, to meeting/contact/account record in CRM?

        Would be useful to keep context and track jobs, better if it will be auto

      • Desk Field Not Showing in Analytics

        Hi there, I recently added a field to our Zoho Desk Ticket Information. I went and added the data retrospectively to the tickets. It is also marked as required, so all new tickets cannot be closed off without it being filled in. When I try to run a report

      • Export data using advanced export options and customizable settings

        Hello everyone, The user interface for exporting data has been revamped with updates to make data exports more flexible and efficient for users. These updates not only enhance usability but also bring advanced capabilities to help users extract precise

      • Moving data from one pipeline to another

        Hey all, I've got some complex pipelines to build and I'd like to seperate them into seperate pipelines rather than have one mammoth one. If I create 2 pipelines, is there any easy way to use the output of Pipeline1 to be the input into Pipeline2? Or

      • How to export/find all deluge code.

        Hi, I have a large app wich contains several forms, reports, html views, I need to find thow my application if any contains specific word, I could find it manually by editing app and see on every section(field code, on succes, on load, etc) but I would like to do it faster. Is there a way to at least export it to a file the whole deluge code on my application?

      • Have Some Bugs in Zoho CRM Ask Zia Assistant

        Hi Support Team, I have found some bugs in Zoho CRM Ask Zia Feature Please Check below screenshot, insight option is showing twice i think its in early access that's why its have some bugs .

      • COD with Partial payment

        Two reasons why we need COD with partial payment option. 1) Since we deal heavy weight products our shipping costs are too high. If shipment is rejected by customer we incur huge loss. 2) Some competitors place fake orders with different names and return

      • Slicers are now available in Zoho Sheet—filter your data interactively

        At Zoho Sheet, we diligently track user requests and feedback. In line with this, based on extensive user requests, we've integrated Slicers to pivot tables and are delighted to announce its release. Slicers are interactive visual filters that have add,

      • Resizing a Record Template Background Inage

        Hi everyone, I have an issue which I can't seem to resolve: Basically, I'm designing a record template in certificate form. I've specified A5 landscape. I've set my background image the same dimensions with total pixels at 443,520. Whatever I try, when

      • Updated font library: New font styles and custom font options in Zoho Sheet

        Zoho Sheet's font library now supports 500+ font styles in 60+ languages! The updated font library is stacked with new font styles, and some of the previously available font styles have been replaced with equivalent options. There are two ways you can

      • Introducing Data Bars: Graphically represent changes in data within the cells

        Conditional formatting has helped millions of spreadsheet users analyze and highlight their data more efficiently. In addition to the classic rules, color scales, and icon sets available in Zoho Sheet, you can now apply Data Bars, a convenient method

      • Default Font Size in Desk

        How do I set my default font size in Desk? It takes me about 45 minutes to find the place to set it, then, when I sign out of Zoho and log back in, it's back to font 10 again. Seems like this would be simple, but like everything with Zoho, it's buried

      • Tip #19 - Create checkbox tracker in your spreadsheet

        Hello Sheet users! We are here with yet another tip to help you get the most out of Zoho Sheet. Spreadsheets can be used to handle a variety of tasks, but ever tried using checkboxes to track the progress of your action items dynamically? Here's a sample

      • Tip #20 - Three things you probably didn't know you can do with picklists

        Hello Zoho Sheet users! We’re back with another quick tip to help you make your spreadsheets smarter. Picklists are a great tool to maintain consistency in your spreadsheet. Manually entering data is time-consuming and often leaves typos and irregular

      • Per Level Approval for admins

        We need Process admins like Zoho CRM in Zoho Books for per stage approval Currently in books, admins only have the option for Final Approval But for example, in cases like when an employee is on leave, we can't just approval one level we only have option

      • Need to set workflow or journey wait time (time delay) in minutes, not hours

        Minimum wait time for both Campaigns workflows and Marketing Automation journeys is one hour. I need one or the other to be set to several minutes (fraction of the hour). I tried to solve this by entering a fraction but the wait time data type is an integer

      • Feature enhancement: Highlight rows based on a cell value

        Hello Sheet users, We're excited to announce a new feature enhacement, shaped directly by your valuable feedback! As you might know, conditional formatting is a great tool for anyone dealing with large data sets. Previously, if you’ve ever wanted to draw

      • Updating custom fields in Zoho Projects

        Hi I am wondering if anyone has experience with custom fields in Zoho Projects. I am struggling to update the field using either deluge or the api endpoint. My code is: //custom_Map = map(); custom_Map = {"UDF_DOUBLE_1":"0.27"}; update_Map = map(); update_Map.put("custom_fields",custom_Map.toList());

      • Markdown for Desk?

        Hi, my company wants to use markdown for formatting text in Desk (in all modules there, especially Tickets and Helpcenter). Zoho already offers use of markdown in several products (see https://help.zoho.com/portal/en/kb/backstage/microsite-guide/formatting-with-markdown/articles/formatting-with-markdo)

      • Change Currency symbol

        I would like to change the way our currency displays when printed on quotes, invoices and purchase orders. Currently, we have Australian Dollars AUD as our Home Currency. The only two symbol choices available for this currency are "AU $" or "AUD". I would

      • Calendar not working

        Are we the only ones. On any browser we cannot click on any of our calendar appointments and get them to open. They just make the browser loop. WE have reached out and have been told they are working on it. The office staff are really stuck. The point

      • Tip of the week #16 - Search and filter threads based on criteria

        Zoho TeamInbox lets you search and filter threads with any information that you have about the thread. You just have to input the criteria and Zoho TeamInbox will list all the threads that match the condition.   Firstly, there is a global search you can

      • WhatsApp Message Template Quick Reply Buttons

        Hello, I created my first Message Template to overcome the 24-hr messaging window and it was approved by WhatsApp/Meta. When I go to Meta, I also see that template brought from Zoho Desk, and used it via Zoho Desk IM. However, I notice that when in Meta's

      • Account in Quick View Filter

        I have a report that I often run against a specific Account. Every time, I have to go into the edit menu and change the Advanced Filter. I would prefer to use the Quick View Filter, but it does not allow me to use the one and only field that makes any

      • Collapsible 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.

      • Set Display for Numbers/Currency/etc with Client Script/Customization in Canvas List Page

        Is it possible to set a display mask for a number/currency field using Client Script or customization? I have custom fields that I would like to keep the decimal places for calculation purposes, but do not need them displayed to the user. So 101.3568

      • 136.143.188.51 blocked by spamcop

        Zoho mailserver seems to be blocked by spamcop. Cant send mail to my customer. Not sure what to do.

      • 🚀 WorkDrive 5.0: Evolving from a file sharing app to an intelligent content management platform: Phase 2

        Hello everyone, WorkDrive's primary focus has always been to provide an intelligent and secure content management platform, simplify collaboration, and be the central repository of files for all Zoho apps. In our previous announcement, we unveiled the

      • Sync desktop folders instantly with WorkDrive TrueSync (Beta)

        Keeping your important files backed up and accessible has never been easier! With WorkDrive desktop app (TrueSync), you can now automatically sync specific desktop folders to WorkDrive Web, ensuring seamless, real-time updates across devices. Important:

      • i keep see there is a connetion issue connecting 3rd party api on zoho when using zia

        hi there , i have set up open ai api to zoho zia (copied and pasted to zoho zia) but I keep getting notificaiton "there is a connetion issue connecting 3rd party api on zoho" when using zia on top when click zia and try to type in word there

      • Deleting Fields in CRM Deletes Views in Analytics

        Hey friends! I'm having some issues when we modify some fields within ZohoCRM. There are times where we need to sunset a field and eventually completely remove it. In these instances, it seems like a lot of views are removed in Analytics. This ranges

      • Booking outside of scheduled availability

        Is there a way for staff (such as the secretary) to book appointments outside of the scheduled availability? Right now to do this special hours must be set each time. There should be a quicker way. Am I missing something?

      • Zoho Desk Android and iOS app update: Access multilingual templates on the IM module

        Hello everyone! We have introduced multilingual templates on the IM module of the Zoho Desk mobile app allowing you to send IM template messages in translated versions. iOS: Android: Please update the app to the latest version directly from the App Store/

      • Does Zoho offer a full WhatsApp Marketing Platform (like WATI / GallaBox)?

        lm exploring WhatsApp marketing and I’d like to understand what options are available within the Zoho ecosystem. Currently, I see: Zoho SalesIQ has a broadcast option, but it seems very limited — for example, it doesn’t support uploading contacts via

      • Custom buttons

        Getting Error "You can only create 10 custom buttons per module" ! I already have more than 10 for 1 module before trying to create another. Is this a new restriction brought about by the all knowing what's best for businesses Zoho guru ? It would be

      • Next Page