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

• Group Tax in Service Line Items

  Hi FSM Team! I noticed that when you update a tax in the service line item the group tax is not showing up as an option. Let me know what can be done thank you!

• Zoho Campaigns - Why do contacts have owners?

  When searching for contacts in Zoho Campaigns I am sometimes caught out when I don't select the filter option "Inactive users". So it appears that I have some contacts missing, until I realise that I need to select that option. Campaigns Support have

• FSM Improvement Idea - Show an Import button when there is no data

  I am setting up FSM for a client and I noticed that there is no option to import data, see screenshot below. Even when you click Create Contact there is only an option to Import from Zoho Invoice. It is only after you add at lease 1 record that the Import

• Whatsapp Limitation Questions

  Good day, I would like to find out about the functionality or possibility of all the below points within the Zoho/WhatsApp integration. Will WhatsApp buttons ever be possible in the future? Will WhatsApp Re-directs to different users be possible based

• Zoho FSM API Delete Record

  Hi FSM Team, It would be great if you could delete a record via API. Thank you,

• Transition from Sole Proprietorship to GmbH (Limited Liability Company) – Best Approach in Zoho Books / Zoho One

  Hello everyone, I am currently operating under a Zoho One plan with a sole proprietorship in Switzerland. As of January 1st, 2026, I will be incorporating a new legal entity – a GmbH (Swiss equivalent of a Limited Liability Company). While the business

• Insert auto number from main form into subform rows

  Hello. I'm trying to take from my main form "order number" which i have setup as an auto generated number into every line created in my subform. So when a row is created in my subform i want the "order number " from the main form to be inserted automatically.

• How to check Leads with no Task (open activity)

  Hi everyone, I was wondering if there’s a way to view leads that don’t have any tasks assigned or open activities linked to them.

• Adding a developer for editing the client application with a single user license

  Hi, I want to know that I as a developer I developed one application and handed over to the customer who is using the application on a single user license. Now after6 months customer came back to me and needs some changes in the application. Can a customer

• Function #4: Schedule Customer Statements

  Regularly sending statements to customers is an imperative part of many business processes as it helps foster strong customer relationships and provides timely guidance on payments. While you can generate the statement of accounts and have it sent over

• Limiting search or dependencies with an asterisk "*".

  I have a form with several dependency fields with options still developing for each field. Since these options were developing and not yet ready to be a selection in the field, I placed a filter for the dropdown field. In this filter, I selected fields

• Collaps Notes

  There are times when long/large notes are added to a record i.e. Accounts or Deals etc. Currently, the full note is displayed in the notes related list section. It would be great if by default only 5 to 10 rows of the note are displayed when the note

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

• Using Zoho Desk to support ISMS process

  Hi, I am evaluating using Zoho Desk for security incident management. This seems to be aligned with Zoho Desk purpose as its just another type of incident. However in security incident management, ideally I can link incidents (tickets) with a risk from

• How to overcome limitations in meetings

  As a company, one of our deliverables is a meeting between two other companies, where we act as facilitators. So, if we recorded this meeting  in Zoho CRM, it should be connected to 2 accounts, 2 contacts, and 1 campaign (a campaign, in our use, is the

• Cross Data Center Support for 1:1 Chats with External Users

  Hello Zoho Cliq Team, We hope you're doing well. We appreciate the recent enhancement that enables cross data center collaboration in external channels, which has already improved communication across distributed teams. However, we’ve noticed that this

• What can we do on our end to improve the Answer bot answers?

  Hi, I'm using the Answer bot card in the Codeless bot builder. I've input several questions and their answers in the FAQ section to feed the Answer bot. The text is all in French, as this is the language our customers communicate in. I've tried testing

• Support Bots and Automations in External Channels

  Hello Zoho Cliq Team, How are you? We actively use Zoho Cliq for collaboration, including with our external developers. For this purpose, external channels are a key tool since they work seamlessly within the same interface as all of our other channels

• Answer Bot and Personalized Questions

  Hi there, I have the same problem using the SalesIQ Answer Bot and the Zoho Desk Answer Bot (which really need different names, to be honest, in order to avoid confusion...) Customers that visit our website ask questions in the form of "What do you do?"

• Handling Greetings/Small Talk at the Beginning of a Zobot Conversation

  Hello everyone, I’m currently configuring a **Zobot** in Zoho SalesIQ and everything is working as expected, except for one specific scenario at the very beginning of the conversation. My target audience has the habit of starting with a **greeting or

• Regex in Zoho Mail custom filters is not supported - but it works!

  I recently asked Zoho for help using regex in Zoho Mail custom filters and was told it was NOT supported. This was surprising (and frustrating) as regex in Zoho Mail certainly works, although it does have some quirks* To encourage others, here are 3 regex

• Importing a new list into campaigns

  I'm in the middle of switching my email platform to campaigns. I have a list that I want to import, and it overlaps with my existing Zoho CRM list. The fields in my Zoho CTM are more robust. Will this new list that I upload into my campaigns overwrite

• Client Script Payload Size Bug

  var createParams = { "data": [{ "Name": "PS for PR 4050082000024714556", "Price_Request": { "id": "4050082000024714556" }, "Account": { "id": "4050082000021345001" }, "Deal": { "id": "4050082000023972001" }, "Owner": { "id": "4050082000007223004" }, "Approval_Status":

• Webform & spam

  Hi, We set up 2 webform on our website, fowarding the content to Zoho CRM. Since it has been opened up, we are getting lot of spam message (for now about 20 a day). To lower the  amount of false new leads we added the captcha field and new enquieries are send to the Approval Leads list. However we still get some spam. Is there any "anti spam" mechanism built in Zoho CRM, or how is the best way to avoid these kind of spam ? Thanks

• when I email a invoice how can i see it was sent and also were i can go to see all emails sent

  when I email a invoice how can i see it was sent and also were i can go to see all emails sent?

• Kaizen #208 - Answering your Questions | Functions, AI and Extensions

  Hello Developers! Welcome back to a fresh week of Kaizen! We are grateful for your active participation in sharing feedback and queries for our 200th milestone. This week, we will answer the queries related to Functions and Extensions in Zoho CRM. 1.

• Export Invoices to XML file

  Namaste! ZOHO suite of Apps is awesome and we as Partner, would like to use and implement the app´s from the Financial suite like ZOHO Invoice, but, in Portugal, we can only use certified Invoice Software and for this reason, we need to develop/customize on top of ZOHO Invoice to create an XML file with specific information and after this, go to the government and certified the software. As soon as we have for example, ZOHO CRM integrated with ZOHO Invoice up and running, our business opportunities

• Showing description in timesheet and timelogs.

  I am wondering if it’s possible in version 5 of Zoho People to have the description show by default or with a manipulation on the user’s part. Let me show you what I mean. As you can see this is the view for the users. Now if they want to see the full

• How can I see content of system generated mails from zBooks?

  System generated mails for offers or invices appear in the mail tab of the designated customer. How can I view the content? It also doesn't appear in zMail sent folder.

• Access Denied

  I am iOS Developer and updating our clients project and shifted ZohoDeskPortalCore SDKs from cocoapods to SPM and changed few lines of code but now i am get access denied, the help center app is unavailable. please contact administrator.

• New in Cadences: WhatsApp follow-ups, upgraded limits, and options for add-ons

  Hello everyone, We're rolling out two key updates to help you engage better and scale smarter with Cadences in Zoho CRM. Reach customers on WhatsApp, directly from Cadences Previously, Cadences have enabled you to automate follow-ups through emails, calls,

• Filtering Tickets based on Email headers

  We're starting to get a lot more junk coming into our Zoho Desk, which is then triggering unnecessary email alerts to agents. Once thing we could do to cut this junk in half, is to filter tickets based on email headers. Any email containing the `List-Unsubscribe`

• CRM Blueprint Notification by Cliq

  Dear Zoho team, In Workflow, there is nofication by cliq, but in blueprint, there is no option as cliq notification. I think it is very convenient to get notified by Cliq , as there are multi modules in apps, but we will always check Cliqs

• Zoho People Attendance Regularization – Wrong Total Hours Displayed

  While using Zoho People, I observed that the attendance regularization is showing wrong total hours when applied to past dates. For example, if a check-in is added at 10:00 AM and check-out at 6:00 PM for a previous date, the system sometimes calculates

• Sync Contacts in iOS

  What does the "Sync Contacts" feature in the iOS Zoho Mail app do?

• Live webinar: Craft the ideal sales pitch deck with Show

  Every great sale starts with a great story. And your pitch deck? That’s where the story takes shape. But too often, these presentations end up looking generic, overloaded with text, or lacking structure. The good news is, it's easier to fix than you think!

• Project Statuses

  Hi All, We have projects that sometimes may not make it through to completion. As such, they were being marked as "Cancelled". I noticed that these projects still show as "Active" though which seems counter intuitive. In fact, the only way I can get them

• 👋 Welcome to the Zoho MCP Community

  Hello all, glad to have you here! This is your space for everything AI agents, MCP tools, and intelligent business apps. This community is for you — developers, partners, creators, and businesses exploring how agents can transform work. Whether you’re

• Suitability of Zoho One (Single User License) for Multi-State GST Compliance & Cost Analysis

  Hello Zoho Team, I am an e-commerce business owner selling on platforms like Amazon, Flipkart, and Meesho, and I'm currently using their fulfillment warehouses. I have two GSTIN registrations and am planning to register for an additional 2-3 to expand

• DNS Manager

  Where Can I find my DNS manager so I can link this to click funnels or AWEBER

• Next Page