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

• get file api is returning Junk data

  I am working on extension development where at one point I need to retrieve attachments on records I found out I can use only invokeconnection and not invokeurl in extension development The invoke connection returns the image in raw binary format. When

• Need help with message box

  End user updates many records at once. Each have unique serial number. They want a confirmation box that says starting number, ending number and qty. Is there any way to do this? I been searching and asking support but seems like no great solution.

• [Webinar] The Transformative Power of Gen BI

  Traditional decision-making tools are no longer enough. The integration of generative AI into business intelligence (BI) is proving to be a true game changer—enabling businesses to make faster, smarter, and better informed decisions. Early adopters of

• Backorder process review - Automating Removal of Sales Order from "On Hold" When PO is Received

  Hello Zoho Inventory Team, Currently, sales orders in On Hold status are released only when the bill for the purchase order is created. In our workflow, it would be much more efficient if the sales order could automatically move out of On Hold as soon

• How to access the saved Query using API?

  I have created a query in setting. Is it possible to access it from a API? What's the endpoint? I tried /v8/queries/important_deals but didnt' work.

• création d'une base de données

  base de donnee d'un lycée

• User Session variables to recall after form submit & redirect to menu

  Hey, Forgive me if this is a simple answer I have overlooked. I have built a big onboarding process for my SAAS platform which is built and managed by an external Dev team. I am hoping to embed my new creator app on the SAAS platform. I have a menu page

• Zoho Writer Merge Template with data from Zoho Analytics Views

  Hello, Is there any way to pull information from Zoho Analytics and put it into a Merge Template? I am trying to create a bulk export of one report that filters on a field to create a single document for each of the filter fields.

• Having to enter bill before stock shows as available.

  Hi, Am I right in thinking you must create a bill from the purchase order receipt before the goods are available for shipping?

• Agent Availability Report

  From data to decisions: A deep dive into ticketing system reports Businesses need to track when their support agents check in and check out from work. This report, titled Agent Availability, is one of the static reports that helps managers track the number

• Writing by Hand in "Write" Notes

  Hi there! I just downloaded this app a few moments ago, and I was wondering if there was a way to write things by hand in "Write" mode instead of just typing in the keyboard. It would make things a bit more efficient for me in this moment. Thanks!

• AI-driven construction analytics using Zoho Projects Plus

  Construction projects thrive on timelines; if a project is completed on or before the expected time, it makes headlines, but if it gets delayed, the company’s credibility will be at risk. Such projects require precise planning and constant monitoring,

• Canadian payroll

  Hello ZOHO, is any updates on when payroll for Canada will be available?

• Unified customer view: Bringing product intelligence into your CRM data

  For businesses today, applications and digital interfaces are the main touch points in the customer journey. While Zoho CRM data already tells who your customers are and what they buy, Zoho Apptics tells you how they interact and engage with your product.

• Zoho Creator SaaS app with multiple client AND multiple users

  I am close to finalizing a Zoho Creator app that will be used by different companies to manage sale info, and each company can have multiple users using the app. Things were going perfectly until I tried a search on a report. I use a database field in each table to separate the data for each company, which works great. BUT when I do a search, I get to see ALL the data. This means that Company A could easily see the data from Companies B and C via the built-in search. Is there a way to set up the

• Project Change Orders and Additions

  We are in the process of migrating from QuickBooks Online to Zoho Books. We have Zoho One and like the ability to sync all of our data across everything. And I like that projects work in a way that's less dumb than QuickBooks. I'm trying to figure out

• Track online, in-office, and client location meetings separately with the new meeting venue option

  Hello everyone! We’re excited to announce meeting enhancements in Zoho CRM that bring more clarity and structure to how meetings are categorized. You can now specify the meeting venue to clearly indicate whether a meeting is being held online, at the

• Create custom rollup summary fields in Zoho CRM

  Hello everyone, In Zoho CRM, rollup summary fields have been essential tools for summarizing data across related records and enabling users to gain quick insights without having to jump across modules. Previously, only predefined summary functions were

• Possible to send Zoom AI Companion transcripts and summaries to contacts in CRM?

  Title says it all. Is it possible to send Zoom AI Companion transcripts and summaries to contacts in Zoho CRM?

• Introducing segments for targeted user engagement

  Hello everyone, We’re excited to announce Segments in Zoho Apptics, a new way to group users based on their behavior, preferences, and app activity. With Segments, you can deliver more meaningful, timely, and relevant experiences to your users. When combined

• How do I edit the Calendar Invite notifications for Interviews in Recruit?

  I'm setting up the Zoho Recruit Interview Calendar system but there's some notifications I don't have any control over. I've turned off all Workflows and Automations related to the Calendar Scheduling and it seems that it's the notification that is sent

• Posibility to add Emoticons on the Email Subject of Templates

  Hi I´ve tried to add Emoticons on the Subject line of Email templates, the emoticon image does show up before saving the template or if I add the Emoticon while sending an Individual email and placing it manually on the subject line. Emoticons also show

• Clarity on extended contract status

  Clarity on “extended” status- How does Zoho “extend” a contract?  E.g. if client extends by 1 month, can the “end date” be adjusted accordingly in Zoho and tagged as “Extended” with a clear audit trail that also captures the client’s email? Note- Email

• Customizing contract status

  Can we customize/add/remove status on Zoho contracts ourselves or does Zoho needs to do this? Context- There is a long list of status on Zoho but not all of them are relevant for us . There are few status which are missing and needs to be added. E.g-

• Set Custom Business Calendars and Holidays for Global Teams

  Managing a project across diverse teams means accounting for more than just tasks and deadlines; it means acknowledging how and when each team actually works. Users might follow different working days or observe region-specific holidays that cannot be

• [Integration edition] Deluge learning series - Integrations between Zoho apps and Third-party services with Deluge | 28 August 2025

  We’re excited to welcome you to the Deluge learning series: Integration edition! The Integration edition will run for three months: Session 1 – Integrating Zoho Apps with Deluge using inbuilt integration tasks Session 2 – Integrating Zoho Apps with Deluge

• Critical Vulnerability in all major password manager plugins - is Zoho Vault affected?

  Hi Zoho, a security researcher found a critical clickjacking vulnerability in all major browser password managers: DOM-based Extension Clickjacking: Your Password Manager Data at Risk | Marek Tóth Is Zoho Vault affected as well? Apparently the Vault extension

• Introducing SecureForms in Zoho Vault

  Hey everyone, Let’s face it—asking someone to send over a password or other sensitive data is rarely straightforward. You wait. You nudge. You follow up once, twice—maybe more. And when the information finally arrives, it shows up in the worst possible

• Tables from ZohoSheets remove images when updated from source

  I have a few tables from a ZohoSheet in a ZohoWriter document that will remove the images in the cells when I refresh from the source. The source still has the images in the table when I go to refresh. After updating from the source, as you can see the

• Change eMail Template for Event-Invitations

  Hello ZOHO-CRM Team How I can change the eMail Template for Event-Invitations? I work with the German Version of the Free Version. I know how I can modify eMail alerts or Signature Templates, but where I can other eMails modify you send out? Thank you for your answer. Regards, Juerg

• Inventory Adjustments

  Hi, How to transfer the material from one head to another ? Like materials purchased for manufacturing the laptop need to transfer from consumption inventory (Quantity of raw materials reduced) to destination inventory ( Quantity of Laptop increased)

• Need Your Insights

  Hi Zoho, I'm confused why the flow only sends to one output. setVariable15 is from a list. It doesn't consider the 2nd entry. Any thoughts?

• Map Dependency Fields - How can can I limit picklist values from a multi-select Parent field?

  I know the "Map Dependency Fields" feature doesn't allow a multi-select parent field. However, I need the functionality. Can I do it through a deluge function, and would it still support color coding picklists? We need the color coding for quick scanning

• DYK 1 - Color Palette for Enhanced Visual Identification of Status

  Introducing the Did You Know series of posts. The goal of this series is to familiarize users with certain features or enhancements in Zoho Projects that may not be evident at first glance. The first post in this series deals with color palettes for indicating

• Invalid field in the COQL query

  Dear Zoho Support! I believe that you already helped me with a similar problem a few years ago. One of my clients has a custom field named "LOB" in the "Deals" Module (see the field's metadata below). The COQL query using this field: : "select id, Deal_Name,

• Automating Employee Birthday Notifications in Zoho Cliq

  Have you ever missed a birthday and felt like the office Grinch? Fear not, the Cliq Developer Platform has got your back! With Zoho Cliq's Schedulers, you can be the office party-cipant who never forgets a single cake, balloon, or awkward rendition of

• Transferring domain registration to new registrar and switching email hosting at the same time?

  I need to transfer an existing domain uv cure adhesive that's currently with SiteGround to Porkbun. I also need to move the existing custom email addresses from SiteGround to Zoho Mail. I'm not sure if I should transfer the domain first and then tackle

• Split deposits

  Can Zoho do split deposits. One deposit, two checks for two separate invoices from different customers. This is one of the most common tasks I can imaging. When I mark the two invoices paid, there are two deposits in bank register. When I try to match,

• Feedback: Streamlining Note Management in Zoho Notebook

  Dear Team/Support, I would like to share some feedback regarding the note management system that could help improve usability and accessibility for users like myself. Notebook 1 (screenshot attached): Currently, the system does not allow selecting and

• Deactivate Desk Contact without Deleting Contat

  We have a client who has multiple tenants for regulatory purposes, and as such, has a few users that have email addresses in both tenants. They've then emailed into the ticketing system, so we have multiple contacts (no big deal, we want to keep their

• Next Page