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 #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 this

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

    • 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

    • Recent Topics

    • Is there a way to show contact emails in the Account?

      I know I can see the emails I have sent and received on a Contact detail view, but I want to be able to see all the emails that have been sent and received between all an Accounts Contacts on the Account Detail view. That way when I see the Account detail

    • Unable to send message;Reason:553 Relaying disallowed. Invalid Domain

      Hi, Now when I try to reply to an email, I see the Unable to send message;Reason:553 Relaying disallowed. Invalid Domain voicemessagedownloader.com error. I tested sending an email when I set it up in the past and it worked. I have checked the Zoho Organization

    • RFID Scanner/Adapter Solution for barcode scanning

      Hello, We will be trialing using barcode scanning for item verification during our picking process. Using a phone or a tablet is awkward and uncomfortable. Are there any Zoho compatible RFID scanners, or an RFID device/adapter that will connect with a

    • Approval Process not retriggering after rejection when stage is manually changed back

      We have an Approval Process on the Opportunities module that triggers when Stage is changed to Negotiation (Execute on: Edit Only). On rejection, a field update action reverts Stage back to Proposal. The issue: after rejection, AE can manually changes

    • Free Webinar Alert! Workdrive + Office Suite in Zoho Workplace: Create, co-edit and collaborate

      Hello Zoho Community! Looking for a better way to create, manage, and collaborate on your business documents? Join our upcoming webinar to discover how Zoho WorkDrive and the Zoho Office Suite (Writer, Sheet, and Show) help teams to work together from

    • Updating Sales orders on hold

      Surely updating irrelevant fields such as shipping date should be allowed when sales orders are awaiting back orders? Maybe the PO is going to be late arriving so we have to change the shipment date of the Sales order ! Not even allowed through the api - {"code":36014,"message":"Sales orders that have been shipped or on hold cannot be updated."}

    • Two-Factor Authentication in Zoho Mail: Add an extra layer of security to your organization

      Account security is a critical aspect of managing any organization's email. With increasing risks of unauthorized access, a single password may not always be sufficient to keep accounts protected. Zoho Mail's Two-Factor Authentication (TFA) addresses

    • Dark Mode - Font Colors Don't Work

      When editing a document in Dark Mode and selecting font colors, they don't show up on screen.  Viewing/editing the same document in Light Mode shows them just fine.

    • API to post drafts for social media

      I we want to post draft posts to our zoho social account and then approve and schedule them within Zoho social. is this possible with for example: https://apis.zoho.com/social/v2/post TIA Jon

    • How to show product cards in your chatbot

      Hey everyone, If you are using Guided Conversations to help customers find products, you have probably run into this problem: the bot gives customers a list of options, but they still have no idea which one to pick. There will be no images, no specs,

    • Changing settings for auto logoff

      I've noticed that when I haven't used Cliq for a while, I have to re-enter my password. That is really clumsy, especially if you have a complicated password. Because it won't be filled in automatically. Is there a way to change that behaviour? We are

    • How do you create invoices before sending them through Zoho Invoice?

      Hi everyone, I'm curious how other businesses handle their invoicing workflow before sending invoices through Zoho Invoice. Do you: Create invoices directly inside Zoho? Prepare them first in another invoice tool or template? Use Excel or Word before

    • ZML Error/Bug

      Hi, I would like to request for your help regarding this kind of behavior. Requested_Start_Time & End_Time - date-time fields https://......#Page:PH_Calendar_Page?reqDate=08-04-2026 https://......#Page:PH_Calendar_Page?reqDate=07-31-2026 https://....#Page:PH_Calendar_Page?reqDate=08-03-2026

    • Item with name in different languate

      Hello, is there a way to have an item with its name in different languages? For example: I sell an item in different markets and I'd like to have a Proposal and the Invoice with the Item Name in a specific language. Rino Bertolotto Zoho Specialist, STESA srl

    • Email notification for followers

      Is there a way to enable email notification for followers of a support ticket? ie: Ticket #123 is owned by Agent#1, Agent#2 adds themselves as a follower. Whenever ticket #123 receives an email from the customer, Agent#1 receives an email. Agent#2 would

    • Migration of emails from Yandex to Zoho

      I am trying to migrate an yandex mail account to zoho mail account. I am confused with all the related articles/informations in the net. Could someone please outline the process to do it, just thinking about me as a novice with limited knowledge or experience. A couple of questions from the knowledge gained. 1. I believe we have to delete the yandex current MX from the website records and add Zoho MX. What happens to the emails as we remove the mail exchange record. Yandex stops updating emails and

    • Auto-fill from logged-in user's profile for Name Fields in Subforms

      Hi, The Name field is great, but I see you can't tick the Initial Value option of "Auto-fill from logged-in user's profile" when it is on a Subform, why not? Thanks Dan

    • I am not able to check in and checkout in zoho people even location access allowed

      This issue i am facing in mackbook air m1, I allowed location in chrome browser and i also tried in safari but getting similar issue. Please have a look ASAP.

    • Calling a function within another function

      Hello there, I have just found out that you can simply call up functions in other functions, regardless of the department. You can't create functions with the same name twice, even though you are in a different department. If you try it, you don't get

    • 【続々公開】Zoholics Japan 2026 セッション情報を更新しました！

      ユーザーの皆さま、こんにちは！ Zoholics Japan 2026のセッション情報を続々と公開しています！ 今年は3つのトラックで、Zohoの最新情報やAI活用、製品アップデート、 活用事例など、多彩なセッションをお届けします。 現在公開中のセッション（一部） ・Zoho CRM 製品アップデート ・Zoho CRM Plus 製品アップデート ・Zoho Community セッション ・Zoho Desk セッション ・中堅・成長企業の人事DX ～AI時代に何から始めるべきか？～ ・Zoho

    • Zoho CRM Community Digest - July 2026 | Part 1

      Hello everyone, July is here! The first two weeks brought six CRM updates ranging from privacy-ready webforms to a significantly more powerful Layout Rules engine, two community wins worth a look (a dashboard workaround for spotting leads with no activities,

    • New Ways to Personalize, Organize, and Share Your Notes

      We're excited to introduce a new set of enhancements in Zoho Notebook that make your note-taking experience cleaner, more flexible, and easier to share. With this update, you can create notes that automatically adapt to your device theme, browse your

    • SPAM (and some other) folders missing on three of my Zoho Mail accounts

      I have four email accounts with Zoho Mail. Three days ago, the Spam folder on three of these accounts vanished. It is gone on the Windows and Linux desktops as well as the web-based and Android versions, and I have tried it on multiple machines. The only

    • Zoho Commerce B2B

      Hello, I have signed up for a Zoho Commerce B2B product demo but it's not clear to me how the B2B experience would look for my customers, in a couple of ways. 1) Some of my customers are on terms and some pay upfront with credit card. How do I hide/show

    • CRM x WorkDrive: We're rolling out the WorkDrive-powered file storage experience for existing users

      Release plan: Gradual rollout to customers without file storage add-ons, in this order: 1. Standalone CRM 2. CRM Plus and Zoho One DCs: All | Editions: All Available now for: - Standalone CRM accounts in Free and Standard editions without file storage

    • Introducing spam detection for webforms: An additional layer of protection to keep your Zoho CRM clean and secure

      Greetings all, One of the most highly anticipated feature launches—Spam Detection in webforms—has finally arrived! Webforms are a vital tool for record generation, but they're also vulnerable to submissions from unauthenticated or malicious sources, which

    • Rich-text fields in Zoho CRM

      Moderation Update: During the initial release of Rich Text fields, it was supported only in the Enterprise and Ultimate editions. We have gradually extended Rich Text fields to all the paid editions of Zoho CRM. Hello everyone, We're thrilled to announce

    • Add Large Lists to Choice-Based Field Rules

      Hi, The new Large List is good, but you can't then use the Choice-Based Field Rules with it to limit the Group Choices or Choices? Thanks Dan

    • Email-Data Synchronization with Zoho Analytics

      Hello, Enterprise Support Community! We're excited to announce the availability of Email Data Synchronization with Zoho Analytics! This highly requested enhancement allows you to sync email data from Zoho CRM into Zoho Analytics, making it easier to analyze

    • Zoho - shopify sales order - invoicing

      we have integrated zoho with shopify. so now , when an order comes through shopify-it raises a sales order in zoho. And at this time- the inventory goes down in shopify, according to the sale. Then we manually convert the sales order to an invoice, and

    • Enable Replenishments Option not Available

      I'm looking to turn on the replenishment option in Zoho Inventory and I'm not finding settings for it in Zoho Books or Zoho Inventory. This is the tutorial I was following from Zoho. Is there a step I'm missing to have Replenishments be available in Zoho

    • Kiosk Page Refresh

      We have a Kiosk running from a button in contacts to update values and also add related lists, which works great, but when the kiosk is finished the page does not refresh to show the changes. Is there a way to force the contact to refresh/update when

    • [Solution] Analyze, Act and Automate with Drill Actions

      Insights create value only when they lead to action. Traditional dashboards excel at helping you understand what is happening, but acting on those insights often requires manual intervention leaving the dashboard, opening another application, finding

    • Building extensions #6: Handling modal boxes to enhance user experience

      In our previous post, we explored creating custom graphical user interfaces using widgets. In this post, we'll learn about enhancing user experience through modal boxes. What is a modal box, and where is it used? A modal box is essentially a widget interface

    • Improve User Onboarding in Zoho Projects with Zoho DAP

      Rolling out new processes or onboarding new users in the tool comes with a familiar challenge: the employees need guidance at the moment they are doing the work. Traditional training sessions and knowledge sharing often require users to leave the application.

    • Zoho Social API for generating draft posts from a third-party app ?

      Hello everyone, I hope you are all well. I have a question regarding Zoho Social. I am developing an application that generates social media posts, and I would like to be able to incorporate a feature that allows saving these posts as drafts in Zoho Social.

    • Your CRO data is now on your AI Assistant: PageSense is live on Zoho MCP

      Hello Everyone, We are excited to announce Zoho PageSense is now live on Zoho MCP servers. Here is what that means for you. Every answer about your website lives behind tons of data across different modules. Which test is winning. Where visitors bail.

    • Feature Enhancement Request – Bulk Download of Signed Documents in Zoho Sign

      Hi Team, We would like to request a Bulk Download feature for signed documents in Zoho Sign. Currently, Zoho Sign allows users to send documents in bulk using an Excel sheet, but there is no option to download the completed signed documents in bulk. Users

    • delete a user on Zoho Desk

      Kindly I Need help to delete a user on Zoho Desk but I deactivated but not deactivated with licenses so what can I Do?

    • Unable to open Attendance Regularization request, reason?

      Unable to open Attendance Regularization request.

    • Next Page