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

    • Announcing the new SKILL.md for Zoho CRM and the updated OAS repository!

      We are introducing a new zoho-crm skill to make working with Zoho CRM Developer tools (like APIs, functions, widgets, client scripts, queries etc) easier and faster, with the help of AI in your preferred AI harness like Claude Code, Codex, Cursor, VSCode

    • Kaizen #256 - Build an Arrival Readiness Web Tab in Zoho CRM

      Hi everyone! Welcome back to the Kaizen series! In the post, we discuss a use case in hospitality industry: how an Arrival Readiness web tab widget can be used to let reception staff identify and resolve issues before arrival of guests. Use case In the

    • 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

    • Recent Topics

    • [IDEA] Bring Layout - Conditional Rules and Client Scripts to Zoho Books

      The problem We run Zoho Books with two e-invoicing integrations: myData (Greek tax authority, AADE) and PEPPOL (EU e-invoicing). Between the two, our Invoice form carries a large number of custom fields — document type codes, VAT exemption categories,

    • Last four Digit field in Zoho Payment Received

      One of our client's payment received doc has Notes, Last four digit and Transaction ID fields set, I couldn't find api parameter for these fields in the documentation... when I checked the site, it's not custom fields as well. where do i find it, any

    • Automatically remove commas

      Team, Please be consistent in Zoho Books. In Payments, you have commas here: But when we copy and paste the amount in the Payments Made field, it does not accept it because the default setting is no commas. Please have Zoho Books remove commas autom

    • Show my cost or profit while creating estimate

      Hi, While creating estimate it becomes very important to know exact profit or purchased price of the products at one side just for our reference so we can decide whether we can offer better disc or not .

    • Cash Flow Forecast Dashboard in Zoho Reports

      I am exploring the capabilities of Zoho Reports and created a simplified Cash Flow Dashboard - http://db.zoho.com/ZDBDataSheetView.cc?DBID=97137000000016024 This is just a sample of the useful financial information for small businesses that can be created with this powerful business intelligence tool from Zoho.

    • Admin Logging in as another User

      How can a Super Admin login as another user. For example, I have a sales rep that is having issues with their Accounts and I want to view their Zoho Account with out having to do a GTM and sharing screens. Latest Update (27th April 2026): With the early

    • Zoho CRM Layout Rules: Nine New Actions, Profile-Based Execution, and Interactive Preview

      Hello everyone, Availability: This feature is now available for all users. We’re excited to announce powerful new enhancements to Layout Rules in Zoho CRM - a feature built to guide our teams through form-filling by showing the right information to the

    • Lookups and Custom Modules

      I created a Custom Module that I'm calling "Item Purchasing Group". This module will store information for groups of Items that must be purchased together (including minimum overall quantities and/or values, etc.). This will have a one-to-many relationship

    • can't access zoho account

      I can't log in to my zoho account, can you help me

    • Auto sync Photo storage

      Hello I am new to Zoho Workdrive and was wondering if the is a way of automatically syncing photos on my Android phone to my workdrive as want to move away from Google? Thanks

    • Has anyone integrated Zoho with Go High Level (GHL)? Looking for guidance

      Hi everyone, I’m exploring the possibility of integrating Zoho applications with Go High Level (GHL) and wanted to check if anyone in the community has experience with this. Specifically, I’m interested in understanding: Whether a direct integration is

    • Updating Unit Code for New Item Creation, Quote and Invoicing is so inconvenient

      The Zoho Team has implemented many updates, but these updates should be optional. Before rolling out any new feature, they should already have a solution in place that allows users to remove or disable it if they choose not to use it. Just yesterday,

    • Item/service subtotal

      Just discovered & really pleased that we can drag to re-order the line items in Sales orders & Invoices, a very nice feature which doesn't seem to be documented? It would be nice to be able to insert a subtotal as a line item to complete this great feature

    • Set Custom Icon for Custom Modules in new Zoho CRM UI

    • I want to prefill CRM Account information using the GSTIN of the Customer

      Currently i need to add account details manually in zoho crm and when it syncs in zoho books manual working needs to be done. Whereas in zoho books i can prefill the customer details using the GSTIN which is great feature. Can the same be enabled for

    • #5 Is This Actually The Right Tool For Me?

      Day 5: Before Meera brought six months of business history into Zoho Invoice, she stopped and asked herself a very sensible question: Is this actually the right tool for me? It is much easier to ask that now than after moving all your data. The Usual

    • Timesheet entry and comment on the actual timesheet

      Dear madam/sir, It would be really helpful if we could add an option to comment on a specific timesheet entry, after the employee logs a time-log. Would that be possible in the future? Or can you suggest another way to do this?

    • OpenAI Is Moving to the Responses API: Here's What It Means for SalesIQ

      OpenAI has deprecated its Assistants API and is moving to the Responses API. If you're using OpenAI Assistants with SalesIQ, you may be wondering if you need to make any changes to your existing setup. You don't. SalesIQ has already taken care of the

    • Need Native Support for docx files in Zoho Writer

      Absolutely love Zoho Writer, but often need to share files by email with people who are in the Office ecosystem. Downloading a file as docx, then sending it by email, getting the comments back, converting it to Zoho format, editing it, then converting

    • CRM integration issues

      hi Just start testing Campaigns. Read up on up on these issues but can not find an answer. I am super admin. 1) its only showing 1002 contacts, I have a 2500 plan which is confirmed in dashboard. I says it sync'd 1400. I've looked at missing contacts,

    • What's New in Zoho Expense: Integrated Business Travel and AI-Powered Expense Management

      This release brings a wide range of updates across Zoho Expense, including new AI-powered capabilities, enhancements to corporate cards, expense management, audits, and more. Keep reading to know how the new updates can transform your travel and expense

    • ChatGPT Plugin / MCP Server auth error

      Hi all I'm trying to connect the ChatGPT plugin for Zoho CRM but after username stage of the auth process, I get this error from the URL https://mcp.zoho.eu/mcp-client/ {"error_description":"Invalid request url, Request is not as per defined in oauth

    • Project Management Platforms for AI Agents: What Matters Most?

      Zoho Projects is already going beyond basic AI assistance with MCP, AI Bridge, and integrations that let AI models access project data and perform actions. That raises an interesting question: what should a project management platform for AI agents actually

    • Sync workdrive feature inside ZohoCRM

      Hi, I'm exploring the new workdrive/ZohoCRM connector released by Zoho to replace the free extension workdriveforCRM which is decomissioned https://marketplace.zoho.com/app/crm/zoho-workdrive-for-zoho-crm I'm rather upset with this long awaited feature,

    • Adding Custom Status Options in Work Order Action Menu

      Hello FSM Team, We would like to inquire if it is possible to add more custom options in the Work Order action/status dropdown (e.g., Cancel, Terminate, Non-Billable, Void, etc.). Currently, the available options are limited, and we are unable to customize

    • MTA - BAD IP reputation by outlook/hotmail

      Messages to Microsoft email servers are bouncing back due to poor reputation. Message: 4.7.650 The mail server [136.143.188.206] has been temporarily rate limited due to IP reputation. For e-mail delivery information see https://postmaster.live.com (S775)

    • Timesheet Task Icons

      In the image below which shows the task field drop down when creating a timesheet against a project and task. What do the icons mean the the right side column against each task? I can't find any documentation or guide that explains what the no entry sign,

    • Open Records in a New Browser Tab

      Hi FSM Team, Just a suggestion: It would be helpful to have a right-click → Open in New Tab option in FSM, similar to CRM. This should ideally work for any clickable record or module, allowing users to open multiple records in separate tabs without losing

    • Facturation électronique 2026 - obligation dès le 1er septembre 2026

      Bonjour, Je me permets de réagir à divers posts publiés ici et là concernant le projet de E-Invoicing, dans le cadre de la facturation électronique prévue très prochainement. Dans le cadre du passage à la facturation électronique pour les entreprises,

    • Marketing Tip #18: Make your online store mobile-friendly to improve traffic

      Most online shoppers browse on their phones first. If your store is hard to read, slow to load, or tricky to navigate on mobile, they’ll bounce fast. A mobile-friendly store doesn’t just look nice; it improves engagement, reduces drop-offs, and helps

    • Cannot add note to record on mobile

      In the latest version of the mobile app - if a record already has notes associated with it - you can add a note via the mobile app - if a record does not have previous notes there is no way to add a new one - it allows me only to send email

    • Custom color coding for your entities

      Our brains are fine tuned to recognize colors before any text or shapes, making color coding a powerful tool to organize data and find items quickly. Color coding of our day-to-day work help with quickly processing the information, reducing cognitive

    • The Social Wall: August 2026

      Hello everyone. Welcome to the August 2026 edition of The Social Wall. This month, we're bringing you updates that make it easier to reach your audience, manage more channels, and streamline your publishing workflow. Here’s what’s new. WhatsApp bulk messaging

    • Check out in Meetings

      Why there is no check out in Meetings of Zoho CRM, very difficult to track

    • How do I get to "Admin Panel"

      I just started a Cliq account. I am the sole administrator. As I read the documentation, I keep seeing reference to an "Admin Panel". I see no way to access this from my Cliq account. How do I access this panel?

    • 【初開催！ オンライン】Zoho Campaigns メール配信の基礎・活用勉強会を開催します！ 10/15 参加無料

      ユーザーの皆さま、こんにちは。 Zoho コミュニティグループの中野です。 Zoho ユーザーコミュニティ初となる、メールマーケティングをテーマにしたオンライン勉強会を開催します！ ▶︎イベント詳細・参加登録はこちら 今回取り上げるサービスは「Zoho Campaigns」です。 「Zoho CRMとZoho Campaignsのどちらからメールを配信すればよいか分からない」 「一斉配信はできるようになったけれど、現在のリスト管理や設定が正しいか不安」 「メールを送るだけで終わり、配信後の改善につなげられていない」

    • Marketing Tip #46: Run flash sales the right way

      A flash sale can do a lot for your store. It can clear slow-moving inventory, spike revenue on a slow day, or reward your most loyal customers. But if done carelessly, flash sales can backfire. Customers start expecting discounts, stop buying at full

    • Introducing Smart Fields in Zoho Forms

      Hello form builders! We are excited to introduce Smart Fields in Zoho Forms - a faster way to add calculations to your forms without writing formulas. Instead of creating multiple fields and configuring complex calculations yourself, you can now drag

    • Checkbox not displaying correctly in subform

      Greetings: I have shared my app (wv) with support.  I am having problems with a checkbox field not displaying correctly in a subform.  The main form is called volunteers and the subform is called volunteers_subform.  The field in question is called roles. When you access the subform by itself the checkbox lookup displays as checkboxes.  But when you view it in the main volunteers form, it displays as a multi-select dropdown instead.   I have attached jpegs showing the difference.   Any thoughts?

    • Unbundle feature for composite items

      We receive composite items from our vendors and sell them either individually or create other composite items out of them. So, there is a lot of bundling and unbundling involved with our composite items. Previously, this feature was supported in form

    • Next Page