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

    • Kaizen #142: How to Navigate to Another Page in Zoho CRM using Client Script

      Hello everyone! Welcome back to another exciting Kaizen post. In this post, let us see how you can you navigate to different Pages using Client Script. In this Kaizen post, Need to Navigate to different Pages Client Script ZDKs related to navigation A.

    • Kaizen #210 - Answering your Questions | Event Management System using ZDK CLI

      Hello Everyone, Welcome back to yet another post in the Kaizen Series! As you already may know, for the Kaizen #200 milestone, we asked for your feedback and many of you suggested topics for us to discuss. We have been writing on these topics over the

      • Recent Topics

      • Tip of the week #27: Edit personal calendars in Zoho Calendar.

        In Zoho Calendar, the personal calendars you create can be edited to make changes you need to make. Edit a Personal Calendar The following changes can be made to the personal calendar by editing it: Calendar title Calendar color Reminders and Description

      • Tip of the week #28: Show/ hide, enable/ disable and empty/ delete your calendars in Zoho Calendar.

        The popularity of online calendars has soared in recent years. It's used both for personal and professional reasons. Calendars have evolved into an effective productivity tool in our lives, from creating events for birthdays and anniversaries to scheduling

      • Tip of the week #30: Share calendars publicly in Zoho Calendar.

        In Zoho Calendar, calendars that are created under My Calendars can be shared publicly. Making your calendar public allows others to view it. When you need to share your calendar with a larger group, public sharing can help. You can restrict others from

      • Tip of the week #31: Share your personal calendars within organization.

        Keep your Organization members aware of what's happening. In Zoho Calendar, you can share your personal calendar with all the members in your organization using the Share with org option.When you enable org sharing for a particular personal calendar,

      • Tip of the Week #33: Appointment scheduler in Zoho Calendar.

        In Zoho Calendar, you can use the Schedule Appointment option to share your appointment request form with the public, allowing people to fill out the form to request an appointment with you. This form can be embedded on your website or blog. Visitors

      • Tip of the Week #34: Embed Calendars using Zoho Calendar

        You can make your calendars public and visible to the general public by embedding them in your websites/blogs using Zoho Calendar. You can use the embed code to add your own calendars to your website's/ blog's HTML code, and the calendar will appear on

      • Tip of the week #35: Migrate to Zoho Calendar from Google Calendar.

        If you are looking to move your Google Calendar events to Zoho Calendar, never worry about missing out the events from your Google Calendar. You can migrate the events from Google Calendar using the export option and import it to Zoho Calendar and manage

      • Tip of the week #36: Migrate to Zoho Calendar from Outlook Calendar.

        If you've been using Outlook calendar and looking to migrate to Zoho Calendar, you can seamlessly export your calendars from Outlook and import them into Zoho Calendar without losing any events, participants, and the reminders set for each event. To migrate

      • Shared calendar issues and duplications

        Apparently there was a calendar update?  Now when I schedule an event for a team member that has shared his calendar with me, the event makes me the organizer and adds the event to my calendar as well.  Previous to this "update" I would scheduled an event

      • Subscribed Calendar

        Hi i have subscribed to a calendar for Holidays in Canada it shows all the holidays perfectly but every one of them has the word Canada before the rest of the name is there a way to remove that word Canada? It takes up a lot of space in the square on

      • The year that was at Zoho Calendar 2023- Part 1

        Hello, amazing community members! Happy new year from all of us here at Zoho Calendar. As we begin the new year, we'd like to thank each and everyone of our community members for your unwavering support and love that you have shown for Zoho Calendar.

      • Zoho Calendar 2024: A Year in Review

        Hello, community members! Happy new year from all of us here at Zoho Calendar. As we turn the page to a new year, we extend our heartfelt gratitude to every member of our Zoho Calendar community for your continued support and enthusiasm. Your feedback

      • Zoho Calendar not syncing correctly with personal Google Calendar

        Coming to this forum as Zoho Calendar support team is not responding, any more. For the past 8 weeks, I have been having an issue with Zoho Calendar not syncing with my personal Google Calendar correctly. I subscribed to Zoho Calendar iCal in my personal

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

      • Zeptomail API error 500 internal server error

        Hi Everyone, getting this eror continuously! Can anyone please guide around the same! Zeptomail API error 500 internal server error Best Regards

      • Waiting multiple days to buy credits, causing my website to suffer

        So I own a fairly large website that gets a lot of registered users. I use transmail send activation emails, and also forgot password emails. I sent an email to zoho's presales team when I was only at 4K/10K emails sent, hoping to buy more credits before

      • Follow up

        Hello, I sent a message 2 days ago but I don't receive any response and I cannot find my ticket here. this is the ticket: Your ticket has been created with the ticket ID 68925465 and subject "Fwd: Fishing-alert" looking forward to seeing your response.

      • What's new in TransMail!

        Note: TransMail is now ZeptoMail. Click here to know more. Hello again, everyone! We've recently crossed the 6 months mark of TransMail's launch. In this time post our launch, we have been constantly working on updating our platform and adding new features

      • June 2021 in TransMail!

        Note: TransMail is now ZeptoMail. Click here to know more. Hello again, everyone! Hope you and your loved ones are doing well. If you're doing less than fine, we truly hope that things only get better for you.  We've had a few updates in the past month

      • TransMail has a new name—ZeptoMail!

        Tried navigating to TransMail's community forum but see a different name now? That's because TransMail has a new name. TransMail is now ZeptoMail! As we’ve grown from an internal service used mainly by other Zoho products to an up-and-coming competitor

      • July 2021 in ZeptoMail!

        Note: TransMail is now ZeptoMail. Click here to know more. Hello again, everyone! Hope you and your loved ones are doing well.  We've had a few updates in the past month in ZeptoMail—some new features and some important announcements. Take look at what

      • Send Email From the ZeptoMail BY API

        What is Zeptomail:- Transactional email service with reliable and fast delivery How we can Create a Connection for Zeptomail in Zoho CRM Go to the Setup Click on Connection Enter Connection Details:- Generate Consumer Key & Consumer Secret Using Zoho

      • Customer email on Opencart 3

        When I place an order, 2 emails are sent: 1) administrator 2) to the user The administrator receives a beautiful letter, but the user receives a damaged letter (see screenshot). What could be the problem?

      • [Announcement] Insert image from URL changes in Zoho Writer

        Hi Zoho Writer users! We'd like to let you know that we've changed the behavior of the Insert image from URL option in Zoho Writer for security reasons. Earlier behavior Once you inserted an image URL in a Writer document, the image would be fetched from

      • Dynamic Signature - Record owner

        Hi everyone, I’m using Zoho Writer merge templates from Zoho CRM and have two questions: Owner signature: How can I automatically insert the CRM record owner’s signature in the merged document? I’m not sure where this signature is stored or how to reference

      • Writer sing up problom

        Zoho writer sing up prolom face

      • Unable to copy into a new document

        Whe I create a new Writer doc and attemp to copy and past I get this message. The only way to copy into a document is I duplicate an existing document, erase the text and save it under a different name and then paste the information. Not ideal. Can you

      • [Webinar] Live demos and user Q&A with Zoho Writer product experts

        Join us on June 12, 2025 for live demos based on your use cases and real-world scenarios raised via form. This is also an opportunity to get your questions answered directly by product experts from the Zoho Writer team. Webinar agenda Live demos based

      • Zoho Writer's built-in citation and bibliography generator

        Hey researchers and writers! Do you manually format citations and bibliographies, spending hours jumping between apps and tabs? If so, then check out Zoho Writer's built-in "Citations and Bibliography" feature. Imagine you're writing a thesis on the future

      • Single and group checkboxes in Zoho Writer's fillable forms

        Hey Writer Fam, Are you making the most out of single and group checkboxes in fillable forms in Zoho Writer? Here is a handy tip to optimize your use of checkboxes, both single and group, and enhance your data collection process. Single checkboxes: Single

      • Collaborate efficiently with Zoho Writer's track changes feature

        Hi Zoho Writer Community, Zoho Writer's track changes feature is a simple, built-in solution that helps you and your team work together efficiently. Instead of juggling multiple versions of a document or building up a long email chain of comments, each

      • Zoho Writer's WordPress extensions

        Hey Zoho Writer users! Say goodbye to all your WordPress content publishing woes with Zoho Writer's WordPress extensions. Publish content with all your formatting and images, republish content when you update a document, and more—from a single window

      • Time-saving table hacks

        Hey Zoho Writer Community, Do you find yourself using a lot of tables in your documents? We're here to share some of our time-saving hacks that will help you work more efficiently, organize your data, and make your documents look neat and professional.

      • Automating document approval and signing with Zoho Writer and Zoho Sign

        Hey Zoho Writer Community! Here's another automation tip to make your processes more efficient! Question: Can I send a document for client approval first, then automatically send it for signing with Zoho Sign if they approve? Since it's the same person

      • Customization hacks in Zoho Writer - Part 2

        Hey community, We're back with some more tricks to personalize your documents, save time, and get in the zone when you work in Writer. Check out part 1 of this post if you haven't already. Let's dive right in! Document ruler units Imagine you're creating

      • Simplify your tax calculations with Zoho Writer

        Hello Zoho Writer Community! Tax season can be stressful, but with Zoho Writer, managing your income tax calculations becomes straightforward and efficient. Here’s an example of how you can use the tables and formulae of Zoho Writer to calculate income

      • Enhance document navigation with headings and TOC

        Hey Zoho Writer Community! We're back with some useful features in Zoho Writer that can simplify your document creation and navigation process. Let's dive right in! Check out our video on how to make the most of Zoho Writer's heading and table of contents

      • Use and download in PDF format of Zoho wirter Merge template using deluge

        Hello Zoho Developers. Here is some information about Zoho Writer. Writer is not just another online word processor, it's a powerful tool for editing, collaboration, and publishing. Even with its wide range of features, Writer's pared-down user interface

      • Customization hacks in Zoho Writer - Part 3

        Hello everyone, Welcome back to Part 3 of our customization tips in Zoho Writer! In this third installment, we'll be diving into some essential customization settings that can enhance your document creation experience. Sender email address in mail merge

      • Daytime saving timezones messing up writer pdf

        Hi, I need help for something I can't figure out. I created a Form to collect data and it is set up with my current Daylight Saving Time (GMT-3). This form is used to generate a contract (pdf Writer) with dates from an event that is being held in 4 months

      • Next Page