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.

Previous Kaizen : Answering Your Questions | Testing and Using REST APIs in Widgets| Kaizen Directory: Home 

• Topic Participants

• Mable Mary M P

  

• Sticky Posts

• Kaizen #197: Frequently Asked Questions on GraphQL APIs

  🎊 Nearing 200th Kaizen Post – We want to hear from you! 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 #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.

• Celebrating 200 posts of Kaizen! Share your ideas for the milestone post

  Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQs

• Kaizen #193: Creating different fields in Zoho CRM through API

  🎊 Nearing 200th Kaizen Post – We want to hear from you! 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.

• Client Script | Update - Introducing Commands in Client Script!

  Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands

• Recent Topics

• Comment Templates

  Is it possible to add a template option for comments? We have some agents in the process who's responses require a pre-formatted layout. It would be incredibly handy to have a template for them where they can insert the template and then add their responses

• [ZohoDesk] Improve Status View with a new editeble kanban view

  A kanban view with more information about the ticket and the contact who created the ticket would be valueble. I would like to edit the fields with the ones i like to see at one glance. Like in CRM where you can edit the canvas view, i would like to edit

• Adding Markdown text using Zoho Desk API into the Knowledge Base

  Hi Zoho Community members, We currently maintain the documentation of out company in its website. This documentation is written in markdown text format and we would like to add it in Zoho Knowledge Base. Do you know if there is REST API functionality

• An Exclusive Session for Zoho Desk Users: AI in Zoho Desk

  A Zoho Community Learning Initiative Hello everyone! This is an announcement for Zoho Desk users and anyone exploring Zoho Desk. With every nook and corner buzzing, "AI's here, AI's there," it's the right time for us to take a closer look at how the AI

• Shared values: From classroom lessons to teaching moments in customer service

  While the world observes Teachers’ Day on October 5, in India, we celebrate a month earlier, on September 5, to mark the birth anniversary of Dr. Sarvepalli Radhakrishnan, a great teacher, renowned scholar, educationist, and advocate for empowerment.

• 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

• Create a list of customers who participated in specific Zoho Backstage events and send them an email via Zoho CRM

  How to create a list of customers who participated in specific Zoho Backstage events and send them an email via Zoho CRM? I was able to do a view in CRM based on customer that registered to an event, but I don't seems to be able to include the filter

• Zoho Desk blank page

  1. Click Access zoho desk on https://www.zoho.com/desk/ 2. It redirects to https://desk.zoho.com/agent?action=CreatePortal and the page is blank. Edge browser Version 131.0.2903.112 (Official build) (arm64) on MacOS

• I hate the new user UI with the bar on the left

  How can I reverse this?

• 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

• Question regarding import of previous deals...

  Good afternoon, I'm working on importing some older deal records from an external sheet into the CRM; however, when I manually click "Add New Deal" and enter the pertinent information, the deal isn't appearing when I look at the "Deals" bar on the account's

• Client Script also planned for Zoho Desk?

  Hello there, I modified something in Zoho CRM the other day and was amazed at the possibilities offered by the "Client Script" feature in conjunction with the ZDK. You can lock any fields on the screen, edit them, you can react to various events (field

• One person/cell phone to manage multiple accounts

  Hi. I have a personal Free account to keep my own domain/emails. Now I need to create a Business account to my company's own domain, but I have only one mobile phone number I use to everything. How do I do to manage this? Can I manage a Free domain and

• Tracking KPIs, Goals etc in People

  How are Zoho People users tracking employee targets in People? For example, my marketing assistant has a target of "Collect 10 new customer testimonials every month". I want to record attainment for this target on a monthly basis, then add it to their

• Zoho Desk: Ticket Owner Agents vs Teams

  Hi Zoho, We would like to explore the possibility of hiding the ‘Agents’ section within the Ticket Owner dropdown, so that we can fully utilise the ‘Teams’ dropdown when assigning tickets. This request comes from the fact that only certain agents and

• Can not Use Attachment Button on Android Widget

  this always pops up when I touch the attach button on android widget. going to settings, there is no storage permission to be enabled. if I open the app, and access the attach feature there, I can access my storage and upload normally.

• Zoho Notebook Sync problem

  I'm facing a problem with syncing of notebook on android app. It's not syncing. Sometimes it syncs after a day or two.  I created some notes on web notebook but it's not syncing on mobile app. Please help!!!!

• Custom Fonts in Zoho CRM Template Builder

  Hi, I am currently creating a new template for our quotes using the Zoho CRM template builder. However, I noticed that there is no option to add custom fonts to the template builder. It would greatly enhance the flexibility and branding capabilities if

• Announcing new features in Trident for Mac (1.24.0)

  Hello everyone! Trident for macOS (v.1.24.0) is here with interesting features and thoughtful enhancements to redefine the way you plan and manage your calendar events. Here's a quick look at what's new. Create calendar events from emails. In addition

• Need Easy Way to Update Item Prices in Bulk

  Hello Everyone, In Zoho Books, updating selling prices is taking too much time. Right now we have to either edit items one by one or do Excel export/import. It will be very useful if Zoho gives a simple option to: Select multiple items and update prices

• Vendor Master Enhancements for Faster Purchase Entry

  I’d like to suggest a few features that will improve accuracy and speed during purchase voucher entry: Automated Item Tax Preference in Vendor Master Add an option to define item tax preference in the vendor master. Once set, this preference should automatically

• Mass Mail Statistics - Number of unsent emails

  How do I find out which emails were not sent?

• Button to add product to cart

  Is there a way to have a button on a page, that when clicked, will add Qty 1 of a product to the cart?

• Est-il possible d'annuler l'envoi d'un mail automatique ?

  Bonjour, Lorsque je refuse un candidat, il reçois un mail dans les 24h pour l'informer que sa candidature n'est pas retenue. J'ai rejeté un candidat par erreur. Savez-vous s'il possible d'annuler l'envoi de ce mail ? Merci d'avance pour votre aide.

• Can't change form's original name in URL

  Hi all, I have been duplicating + editing forms for jobs regarding the same department to maintain formatting + styling. The issue I've not run into is because I've duplicated it from an existing form, the URL doesn't seem to want to update with the new

• New in Cadences: Option to Resume or Restart follow-ups when re-enrolling records into a Cadence, and specify custom un-enrollment criteria

  Managing follow-ups effectively involves understanding the appropriate timing for reaching out, as well as knowing when to take a break and resume later, or deciding if it's necessary to start the follow-up process anew. With two significant enhancements

• embed a form in an email

  Hello, how to embed a form in an email that populates Zoho CRM cases? I would like to send emails to a selected audience offering something. In the same email the recipients - if interested - instead of replying to can fill in a Zoho CRM form that creates

• Zoho Bookings - Reserve with Google

  Does Zoho Bookings plan to to integrate with Reserve with Google?

• How to add Zoho demo site page designs to my Zoho Sites website

  Hi, I would like to add the design from the following demo URLs into my current Zoho website. I have already created two new pages on my site, named “Menu2” and “Menu3.” For the “Menu2” page, I want to use the design from this demo: https://naturestjuice-demo.zohosites.com/menu

• Digest Août - Un résumé de ce qui s'est passé le mois dernier sur Community

  Bonjour chère communauté ! Voici le résumé tant attendu de tout ce qui a marqué Zoho le mois dernier : contenus utiles, échanges inspirants et moments forts. 🎉 Découvrez Zoho Backstage 3.0 : une version repensée pour offrir encore plus de flexibilité,

• Global Sets for Multi-Select pick lists

  When is this feature coming to Zoho CRM? It would be very useful now we have got used to having it for the normal pick lists.

• Text snippet

  There is a nice feature in Zoho Desk called Text Snippet. It allows you to insert a bit of text anywhere in a reply that you are typing. That would be nice to have that option in Zoho CRM as well when we compose an email. Moderation Update: We agree that

• Kaizen #206 - Answering your Questions | Displaying Related Purchase Orders from Zoho Books in CRM Deals using Queries

  Hello everyone! We're back with another post in the Kaizen series. We're grateful for the feedback we received from all of you! One of the questions we received was "I would like to see the list of Purchase Orders in Zoho Books for a Deal in CRM." We

• Add Analytics function for Title case (capitalising each word in a string)

  At present, you can only capitalise each word in a string in Analytics during data import. It would be really useful to be able to do this with a formula column, but there is no Title Case function.

• How to conditionally embed an own internal widget with parameters in an html snippet?

  Hello everyone, I'm trying to create a dynamic view in a page using an HTML snippet. The goal is to display different content based on a URL parameter (input.step). I have successfully managed to conditionally display different forms using the following

• Introducing AI-powered Assessments & Zoho's native LLM, Zia

  We’ve shipped a cleaner, faster way to create assessments in Zoho Recruit. 🚀 Instead of manually building question banks or copying old templates, you can now generate ready-to-use assessments in just a few clicks, all tailored to the role you’re hiring

• Where can I find rejected inbound mails and their reason for rejection

  Hi, I was recently made aware by a mailing list which I am subscribed to (ffmpeg-devel@ffmpeg.org) that my Zoho mail Mail account is rejecting some emails. If I look under Admin Panel > Security & Compliance > Quarantine > Incoming, the list there is

• Sync more than one Workdrive

  Hello Please I'm facing some difficulties since some days. In my company we have many zoho accounts in different organisations. And I have to find a way to sync all these Workdrives. I spend many hours to search it on zoho Workdrive but no solution. Could someone help me ? Any idea how I can achieve it ? Thanks in advance. Regards

• 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

• Base Currency Adjustment Reversal

  Two questions surrounding the base currency adjustments (BCA). I recently ported over from QB so I need to enter the base currency adjustments. In QB, it will calculate the BCA for you at the end of the year and then reverse it at the top of the following year. Makes sense. Does Zohobooks not do this as well? I created a BCA for Dec 31, 2016 but no reversing entry was made Jan 1, 2017. Am I supposed to manually do a reversal? I'm not even allowed to post journals directly to the 'exchange gain loss'

• Next Page