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.


      Zoho Campaigns Resources


        • Desk Community Learning Series


        • Digest


        • Functions


        • Meetups


        • Kbase


        • Resources


        • Glossary


        • Desk Marketplace


        • MVP Corner


        • Word of the Day


        • Ask the Experts


          • 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

          Zoho CRM Plus Resources

            Zoho Books Resources


              Zoho Subscriptions Resources

                Zoho Projects Resources


                  Zoho Sprints Resources


                    Zoho Orchestly Resources


                      Zoho Creator Resources


                        Zoho WorkDrive Resources



                          Zoho CRM Resources

                          • CRM Community Learning Series

                            CRM Community Learning Series


                          • Tips

                            Tips

                          • Functions

                            Functions

                          • Meetups

                            Meetups

                          • Kbase

                            Kbase

                          • Resources

                            Resources

                          • Digest

                            Digest

                          • CRM Marketplace

                            CRM Marketplace

                          • MVP Corner

                            MVP Corner




                            Zoho Writer Writer

                            Get Started. Write Away!

                            Writer is a powerful online word processor, designed for collaborative work.

                              Zoho CRM コンテンツ



                                ご検討中の方

                                  • Recent Topics

                                  • Zoho Voice lance BYOC (Bring Your Own Carrier) : intégrez votre opérateur

                                    Pour accompagner sa croissance, une entreprise a besoin d’une infrastructure téléphonique flexible et évolutive. Les solutions de téléphonie s’adaptent aux exigences du centre de contact, tout en intégrant aisément les opérateurs locaux de votre choix.
                                  • Zoho Recruit Slow and Freezing on all screens

                                    We have had an issue with Zoho Recruit for weeks being extremely slow and at times freezing.  We have 100 mega internet, and I went into each computer and updated the virtual memory so there is more available.  Also restarted all computers daily.  Still having the issues.  Almost unable to work.
                                  • Prevent accidental duplicate entry of Customer Ordersome

                                    Zoho Support has confirmed that Zoho currently does not have any method (using Deluge, flow or any other method) to alert a user when a sales order has been entered twice using the same customer reference number (i.e. a duplicate). Most ERP platforms
                                  • Zoho Books | Product updates | November 2025

                                    Hello users, We’ve rolled out new features and enhancements in Zoho Books. From translating email notification templates to the new transaction locking restrictions, explore the updates designed to enhance your bookkeeping experience. Making Tax Digital
                                  • Insert Image into Notebook page

                                    Prior to today, I could add images to my notebook pages. Today when I tried to do this I got an error message that said something like, "There's been a problem on our end. Try again later." So, I've tried all the ways I know how, but I can't insert an
                                  • 【開催報告】名古屋 ユーザー交流会 Vol.2 2025/11/21 Zoho Analytics / Inventory で実現する在庫の"未来予測"

                                    ユーザーの皆さま、こんにちは。コミュニティチームの中野です。 11/21(金)に名古屋 ユーザー交流会 を開催しました。 本投稿では、当日実施したセッションの様子及び投影資料をお届けします。 会場にて参加できなかった皆さまも、ぜひご参照ください。 (Zoho 社員セッションの登壇資料については、11/28(金)開催の東京回の開催報告で共有いたします) 今年2回目の開催となる名古屋 ユーザー交流会では、株式会社エンツナクリエイト 野末さんによる Zoho Analytics / Inventory
                                  • Is there a way to automatically add Secondary Contacts (CCs) when creating a new ticket for specific customers?

                                    Some of our customers want multiple contacts to receive all notifications from our support team. Is there a way to automatically add secondary contacts to a ticket when our support team opens a new ticket and associates it with an account? This would
                                  • Improved RingCentral Integration

                                    We’d like to request an enhancement to the current RingCentral integration with Zoho. RingCentral now automatically generates call transcripts and AI-based call summaries (AI Notes) for each call, which are extremely helpful for support and sales teams.
                                  • Edit Pinned Comments in Zoho Desk

                                    It's great that private comments can now be pinned to the top of the ticket but what would be extremely helpful would be to allow for the pinned comment to be edited vs. having to find the comment in the ticket to edit it.
                                  • Updating Secondary Contact (CCs)

                                    We use Zoho Forms to capture the user request and integrated with Zoho Desk to raise tickets. Active Microsoft login is captured in our Zoho forms and registered as Primary contact in Zoho desk ticket. We also an have an option to raise ticket on behalf
                                  • blank page after login

                                    blank page after logging into my email account Thanks you
                                  • WriterTh

                                    After every space Writer goes to capital letters mode in my Android tablet. The cap mode stays till the second letter is typed in the word then it comes to normal mode.
                                  • Zoho writer unable to merge documents to PDF with basic fonts in Hebrew or fonts from my computer

                                    I created several forms that will be merged into PDF files through Zoho Writer and I am unable to receive the PDF in the basic fonts of the Hebrew language or in the fonts I have on my computer. The writer exports to PDF an exchange font that looks very
                                  • I have already created some Bots, Commands, and Widgets in Cliq, but I am still not seeing the “Create Extension” option in my account. Could you please help me enable or access this option?

                                  • How to setup DKIM / SPF in Zoho Mail

                                    Hello there! I'm having a hard time understanding how to setup the TXT records for SPF and DKIM with Zoho Mail. I'm following the instructions here: https://www.zoho.com/campaigns/help/setup-spf-dkim.html Specifically, when it comes to the value for the
                                  • Cliq iOS can't see shared screen

                                    Hello, I had this morning a video call with a colleague. She is using Cliq Desktop MacOS and wanted to share her screen with me. I'm on iPad. I noticed, while she shared her screen, I could only see her video, but not the shared screen... Does Cliq iOS is able to display shared screen, or is it somewhere else to be found ? Regards
                                  • Infinite loop of account verification

                                    Hi I can't do anything on my zoho account.  I always get this message Hi Sheriffo Ceesay As a security measure, you need to link your phone number with this account and verify it to proceed further. When ever I supply the details, it displays that the number is associated with another account. I don't have any other account on zoho so this is really annoying. 
                                  • How we cut CRM updates from ~20 minutes down to 2, our real workflow

                                    Updating the Zoho CRM after every call used to be one of the biggest time sucks for our team. By the time you write your notes, clean them up, fill in the fields, and log everything properly… you’ve easily lost 15–20 minutes per call. We started experimenting
                                  • Arattai App Features Update

                                    1. Offline Messaging & Sync Enable users to compose messages without internet and deliver them automatically via peer-to-peer methods (Bluetooth/WiFi Direct) when nearby users are available. This would be a game-changer for rural India with unreliable
                                  • Zoho Books Sandbox environment

                                    Hello. Is there a free sandbox environment for the developers using Zoho Books API? I am working on the Zoho Books add-on and currently not ready to buy a premium service - maybe later when my add-on will start to bring money. Right now I just need a
                                  • How to add Product Add-Ons, Mandatory Forms, and Auto-Save Address in Zoho Commerce

                                    Hi all, I need help setting up several behaviors in Zoho Commerce. I can’t find the correct configuration options, so I want to confirm whether these are supported or if there is a workaround. 1. Product-Specific Add-Ons (Example: GWB Subscription) When
                                  • Request for Auto PO - Min–Max based Automated Purchase Feature

                                    Dear Zoho POS Team, I’m writing to request a feature enhancement that would significantly streamline inventory management for businesses using Zoho POS — particularly supermarkets, FMCG retail, and multi-store operations like ours. Feature Requested:
                                  • Zohomail

                                    Im trying to setup email address zoho
                                  • PROBLEMA

                                    Salve, non riesco a inviare email, e mi esce una tabela errore temporaneo. come posso risolvere il problema ?
                                  • Forever FREE Business Email with Zoho Mail

                                    Forever FREE Business Email with Zoho Mail: is it available?
                                  • Weekly Tips : Make collaboration effortless with Whiteboard in Zoho Mail

                                    Working with your team often means switching between emails, notes, and other applications just to explain an idea. Maybe you are trying to sketch a layout, plan a workflow, or quickly brainstorm ideas—with text alone, things can get confusing. So how
                                  • Formula field number of days between 2 dates

                                    Hi, I want to have a formula field which calculates the following: IF EndDate < TODAY and Oproep is true (this is a checkbox field) than EndDate - StartDate, otherwise TODAY - StartDate It should calculate the number of days How can I write this for
                                  • Tracking Snippet not working in Zoho Marketing Automation!

                                    First off, the fact that you have to wait about 12-24 hours for every response is terrible. How are we supposed to conduct business? Second, we have been trying for several days to get the Tracking Code Snippet in marketing automation to work, to no avail.
                                  • 'email address already exists'

                                    I deleted a user from my organization and want to use the same email address that user had, but the email address seems to still exist somewhere as I get 'email address already exists' when I try and create it. I have deleted the entire organization and
                                  • ZOHO reporting DKIM entries are not configured, when they have been configured and verified by 3rd parties

                                    Why is ZOHO reporting to my organisation users the following: "The DKIM entries in your domain's DNS records are not configured. Please contact your administrator for configuring DKIM to ensure optimal RSVP invite delivery." When I have configured the
                                  • Manage Bookings directly from Zoho Mail

                                    Greetings from the Zoho Bookings team! We’re introducing the new Zoho Bookings extension for Zoho Mail, designed to help you view appointments, copy time slots and share booking links without leaving your inbox. This integration brings scheduling right
                                  • My notes from the past 2 months have disappeared

                                    Hola, necesito ayuda urgente. Hoy, al iniciar sesión en mi Zoho Notebook como todos los días, me llevé una gran sorpresa al descubrir que todas mis notas de los últimos dos meses habían desaparecido. Estas notas son muy importantes para mí, ya que uso
                                  • How can I load a network into the cliq desktop app?

                                    I have both the standard cliq log in for my org and I am part of a cliq network. In the browser I can choose which I log in to. However, in teh desktop app if I log in it will alwasy load my org's cliq. Can I switch this to the network I have create
                                  • Ability to modify what displays in calendar invite?

                                    I am a long time calendly user and want to make the switch to bookings.  I understand that there is not currently a meets/hangouts integration, is one on the roadmap? Is there anyway I can modify the calendar invite to include the meet link?  I can add it to the emails no problem, but I would also like it to display on their calendar.  Is there some work around I can do to get it on the calendar?  Also am I able to modify the calendar event title?
                                  • Issue with Booking Confirmation Page Not Displaying, Leading to Customer Anxiety and Unnecessary Support Calls

                                    I am writing to express my growing concern regarding the confirmation process in Zoho Bookings, particularly the inconsistent display of the confirmation page after a successful payment. As a mobile service provider, I rely on Zoho Bookings platform for
                                  • Is it possible to turn off all capabilities for a customer to schedule, reschedule or cancel an appointment?

                                    Is it possible to turn off all capabilities for a customer to schedule, reschedule or cancel an appointment? I would like to set it up so only staff can schedule appointments. Is this possible?
                                  • Is there a way to generate a virtual meeting for a group service in Zoho Bookings?

                                    Are virtual meetings not supported for group services/meetings? I have integrated Zoom with one-on-one services, but I need a way to create an online group meeting. Thanks
                                  • Introducing VeriFactu Support in Zoho Books

                                    Hello users, Spain has introduced the VeriFactu system under Real Decreto 1007/2023 to ensure integrity, traceability, and anti-fraud compliance in e-invoicing. Starting January 1, 2026, all B2B invoices must be reported to Agencia Estatal de Administración
                                  • Where we can change the icon in social preview

                                    Hi, we changed our logo, and the image that appear in preview (ex : when we post a appointment link somewhere) is still our old logo. I did change our logo in the org setting. https://bookings.zoho.com/app/#/home/dashboard/settings/basic-info?clview=false
                                  • Zoho Bookings changes Lead Source

                                    Hi. i would like to know if there's a way for Zoho Bookings to not change the lead source when booking a lead for an appointment as the lead source will be used in a report. Scenario: Lead source: Website after booking an appointment Lead source: Zoho Bookings Thanks. Dan
                                  • Next Page