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

    • Kaizen #152 - Client Script Support for the new Canvas Record Forms

      Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved

    • Recent Topics

    • What is the safest way to convert OST to PST files?

      The safest way to convert OST to PST files is by using a reliable and professional OST to PST Converter tool. Manual methods often risk data loss, corruption, or dependency on Exchange Server connectivity. A trusted converter Aryson OST to PST Converter

    • Zoho CRM for Everyone's NextGen UI Gets an Upgrade

      Hello Everyone We've made improvements to Zoho CRM for Everyone's Nextgen UI. These changes are the result of valuable feedback from you where we’ve focused on improving usability, providing wider screen space, and making navigation smoother so everything

    • Social icons, open in new tab?

      Hello, I have two social icons on my footer, Facebook and Psychology Today. Clicking on the Facebook icon opens a new tab, the Psychology Today icon does not. I would like them both to open a new tab. Am I missing a setting somewhere?

    • Introducing Connected Records to bring business context to every aspect of your work in Zoho CRM for Everyone

      Hello Everyone, We are excited to unveil phase one of a powerful enhancement to CRM for Everyone - Connected Records, available only in CRM's Nextgen UI. With CRM for Everyone, businesses can onboard all customer-facing teams onto the CRM platform to

    • Real-Time Screen Annotation During Zoho Cliq Screen Sharing

      Hi Zoho Support Team, Hope you're doing well. We’d like to request the addition of real-time screen annotation tools during screen sharing sessions in Zoho Cliq video calls. 🔍 What We're Looking For: The ability for the presenter—and optionally, other

    • encountering an error when attempting to associate an email with a Deal using the Zoho CRM extension in Zoho Mail.

      When I click "Yes, associate," the system displays an "Oops!! Something went wrong" error message. I have attached a screenshot of the issue for reference.

    • Autofill address using smart fields mapped over the pdf document

      Hi, I'm using mail merge to map smart fields onto PDF documents I plan to distribute for signing. I already have a Zoho Sign subscription. When mapping smart fields from the Employee form, I only see the permanent and current addresses which include the

    • Live Chat for user

      Hi everyone, I’m new to Zoho Creator and wanted to ask if it’s possible to add a live chat option for all logged-in portal users so they can chat internally. I’m trying to create a customer portal similar to a service desk, but for vehicle breakdowns,

    • How do I cap employee leave accrual

      HI there, How do I cap an employee's leave accrual? The policy is that you accrue 15 days leave annually (1.25 days a month) and once you reach 15 days, you wont accrue more until you take leave. Thank you!

    • Open sub form from a button as a popup form

      Is there a way within a form to use similar code as below to show a button in the form when clicked opens the subform for data to be added to the record being viewed in the form OpenUrl("#Form:<Customer_Delivery_Address>?<Delivery_Address>=" + input.ID,"popup

    • Dont have backup option in setting

      Hi guys. I started using zoho book a week ago. I bought premium package yet I don't have backup option in setting. I hope anyone can help me find a solution. Thanks in advance

    • Making Tags Mandatory

      When creating an expense, is it possible to make the Tags field mandatory?  I see the option in settings to make other fields mandatory, like Merchant, Description, Customer, etc, but nothing about Tags. Thanks! Kevin

    • Is there a plan to integrate zoho voice with zoho books?

      Hello, Is there a plan to integrate zoho voice with zoho books? Right now we are using the Twilio SMS integration into zoho books, but have recently decided to switch to zoho voice for calls and sms. Is there a plan to integrate zoho voice natively into

    • Pass variables to Zoho Desk via URL to create a fast new ticket landing page

      We are integrating our phone system into Zoho Desk. Currently when a helpdesk agent answers the phone, a soft client opens a new tab with zoho desk at the new case page. https://desk.zoho.com/support/companyname/ShowHomePage.do#Cases/new We would like

    • Zoho Books Extension: What Happens If Custom Fields Already Exist?

      When developing Zoho Books extensions, what happens if the target Zoho Books organization already has a custom field with the same API name as one defined in the extension? I’m asking because we originally created an on-Books version of this functionality,

    • Modular Permission Levels

      We need more modular Permissions per module in Books we have 2 use cases that are creating problems We need per module export permission we have a use case where users should be able to view the sales orders but not export it, but they can export other

    • ¡Vuelven los Workshops Certificados de Zoho a España!

      ¡Hola usuarios de Español Zoho Community! Hace ya unos días que hemos dado la bienvenida al 2026, y promete ser un año de lo más emocionante. Y es que nos gustaría haceros nuestro particular regalo de Reyes, aunque lleguemos un poco tarde. 🎁 ¡Nos gustaría

    • Free Webinar on 21 January: Looking back at Zoho Mail in 2025

      Hello Zoho Community! Curious about how Zoho Mail evolved in 2025? Wondering how these updates can make your everyday email work simpler? We’ve got a session you won’t want to miss. In our Zoho Mail 2025 recap webinar, we’ll walk you through the key features

    • Delay in rendering Zoho Recruit - Careers in the ZappyWorks

      I click on the Careers link (https://zappyworks.zohorecruit.com/jobs/Careers) on the ZappyWorks website expecting to see the job openings. The site redirects me to Zoho Recruit, but after the redirect, the page just stays blank for several seconds. I'm

    • Cliq Networks users can see all other network users contact information

      Is there a way to hide user contact information from each user in networks? I would only like the users to see the admin's contact information, not other users. Network users information shared by default

    • Zoho Sheet - Printing - Page Breaks and Printing Customization

      I think the title is descriptive enough in that I cannot find help documentation on a simple task of adding in page brakes for separating pages on print. Thanks

    • Missing the "Find & Merge Duplicates" choice

      Hi, I am missing the "Find & Merge Duplicates" choice. I looked under the "More Actions" menu in Contacts, Accounts, Vendors, and Leads and it is not there. I have full permissions. Please assist me on finding this feature. Thanks!

    • OAuth integration issues

      I'm experiencing persistent OAuth errors when trying to connect Make with Zoho API. I've tried multiple approaches but keep encountering the following issues: First error: 'Invalid Redirect Uri - Redirect URI passed does not match with the one configured'

    • Marketing Tip #16: Ideal sizes and formats for adding images to your online store

      Images can make (or break) your storefront experience. When your banners and product photos follow the right sizes and aspect ratios, your store looks cleaner, loads faster, and feels more trustworthy—especially on mobile. Here are recommended image sizes

    • Improve WhatsApp Module in Zoho CRM

      The current WhatsApp module UI in Zoho CRM feels cluttered and complex, especially when handling high volumes of conversations. It would be great to enhance the WhatsApp module UI/UX by adopting a clean and simplified interface similar to Bigin CRM’s

    • Blueprint transitions on locked records

      We use the ability to automatically lock records (quotes, sales orders, etc.) based on criteria, such as stage. For instance, if a quote has been sent to a client, the quote is then locked for further edits. Our ideal quote stage process is: Draft>Sent>Won.

    • Enhance productivity with the revamped Zoho Sheet View

      Hello folks, For some time now, you've been able to use the Zoho Sheet View to quickly edit multiple records or to insert a batch of new records. Its tabular interface allows users to engage in these tasks productively. Despite this, the existing Sheet

    • No OR Filter for Views with a Related Modules Criteria

      We would like to create a Deal View where the User can see all their deals. For that, we would need an OR to connect the criteria. One of the Fields is a "multiselect User", these (Related Modules Criteria) can only be Filter with an AND. Even between

    • Good news! Calendar in Zoho CRM gets a face lift

      Dear Customers, We are delighted to unveil the revamped calendar UI in Zoho CRM. With a complete visual overhaul aligned with CRM for Everyone, the calendar now offers a more intuitive and flexible scheduling experience. What’s new? Distinguish activities

    • Limit maximum entries for subform - depending on fields entry

      Hi Zoho! I have a form with a subform in it. I'd like to have limitation for the row number depending on an entry in a drop-down field in the main form (If the field in the main form is marked "Answer1" - Limit the entries to 1 row, if the field is "Answer2" to have 2 rows limitation, "Answer3" = no limitation at all) Can this be done? Thanks Ravid

    • Save HTML Snippet Page as PDF with Dynamic Data in Zoho Creator (Working Solution)

      Hi Zoho Creator Community 👋, I faced a common challenge while working with HTML Snippet Pages — I needed to generate a PDF with dynamic data and save it back into the record automatically. Here’s the working solution that might help others. Use Case

    • Make Camera Overlay & Recording Controls Visible in All Screen-Sharing Options

      Hi Zoho WorkDrive Team, Hope you are doing well. We would like to request an improvement to the screen-recording experience in Zoho WorkDrive. Current Limitation: At the moment the recording controls are visible only inside the Zoho WorkDrive tab. When

    • Cannot connect to imap.zoho.eu on iOS26

      Hey, I recently migrated to another iPhone and since then use iOS26. Every since then, I was not able to connect to "imap.zoho.eu" from Apple Mail. I tried deleting the account and adding it again, did not work. I tried creating an app password, didn't

    • Rebranding Options for Zoho One

      We need the addition of rebranding and white-labeling settings directly within the Zoho One Admin Panel. This feature should allow organizations to customize the unified portal with their own logo, brand colors, and custom domain mapping (e.g., portal.company.com).

    • Tip #57- Accessibility Controls in Zoho Assist: Mobility- 'Insider Insights'

      Remote support should be easy to navigate for everyone. For users with mobility-related accessibility needs, long sessions and complex navigation can be challenging. Zoho Assist’s Mobility Accessibility Controls simplify interaction through keyboard-based

    • To print Multiple delivery notes in batches

      In Zoho Books, we can print a Delivery Note from an Invoice using the Print Delivery Note option, but it is non-editable and always prints all line items from the invoice. Our requirement is to deliver invoiced items in batches and print delivery notes

    • UPLOAD A CREATED PDF AUTOMATICALLY

      Using the html header pdf+print button, I have managed to find a way to have a user create a pdf using entered form data. Using the schedule button, I can have a "file uploaded" pdf mailed to someone as an attachment. The missing piece is to be able to add the pdf, created in that html page to a file upload field automatically? Right now one has to save it to computer and then upload it in a FILE UPLOAD FIELD. Any help would appreciated !  

    • Consolidated Department-wise Payroll Cost Summary Report

      Hello Zoho Payroll Team and Community, I am writing to discuss a reporting requirement regarding department-level expense tracking within Zoho Payroll. As we scale and manage salary distribution for employees across multiple departments, such as Accounts,

    • Write-Off multiple invoices and tax calculation

      Good evening, I have many invoices which are long overdue and I do not expect them to be paid. I believe I should write them off. I did some tests and I have some questions:  - I cannot find a way to write off several invoices together. How can I do that,

    • How to remove chat icon from knowledge base?

      I have set up a knowledge base to hold FAQs and documentation. It is currently standalone, and not integrated into our website. On every page there is a chat button in the bottom left corner that says "We're offline, please leave a message." How can I

    • Next Page