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

    • 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

    • Recent Topics

    • Zoho rejecting external email – “Email policy violation detected”

      Hello, I was informed by external senders that their emails to my addresses were rejected by Zoho Mail. The emails were sent from external domains (including pfms.ba.gov.br domains), not from my own domain. However, Zoho rejected the messages with the

    • unable to log in on iphone and unable to log in one auth

      im unable to log in to my mobile

    • Tip #48: An exclusive system for risk management

      Zoho Sprints' risk management feature gives teams a structured, industry-grade system for identifying, quantifying, and mitigating risks to eliminate probable impact. Project or product teams that run on Zoho Sprints might be using sprints, work items,

    • Follow-Up: No Response to Previous Inquiry on Workplace Plan Scalability

      I have previously sent a few emails to your support address but have not received any response. I am unsure whether my messages are being delivered successfully or possibly filtered as spam. My most recent inquiry was regarding clarification on user scalability

    • Unable to receive any email

      Hello I have several problems. I am unable to receive any emails sent to my Zoho account. Also, when I send an email, my account appears in the spam folder, and my profile picture doesn't appear; instead, a question mark appears.

    • Edit a previous reconciliation

      I realized that during my March bank reconciliation, I chose the wrong check to reconcile (they were for the same amount on the same date, I just chose the wrong check to reconcile). So now, the incorrect check is showing as un-reconciled. Is there any way I can edit a previous reconciliation (this is 7 months ago) so I can adjust the check that was reconciled? The amounts are exactly the same and it won't change my ending balance.

    • Not able to receive mails

      Am able to send mails. But not able to receive. The mail bounces back saying Your message wasn't delivered because the address couldn't be found, or is unable to receive mail.

    • Loading Zoho Webmail

      Zoho Webmail don't work. Yesterday webmail works in the same web browser (Firefox). Webmail works on google chrome. Try to repair for Firefox.

    • Account blocked

      My account contato@fernandovarella.com.br was blocked due to suspicious login activity. I am the owner of the account and domain. Please unblock web access and outgoing mail.

    • Can anyone tell me my setup right or wrong?

      Tell me about this, my root domain not receive mails from other senders, only receiving from mails connected with zoho network , i have to need sender.net camp... also For MX MX | dandakaranya.com | mx3.zoho.in | 50 | Auto MX | dandakaranya.com | mx2.zoho.in

    • Cannot sign up customer for Zoho Mail

      I tried last morning to sign up a customer for Zoho Mail, but it says it is unable to create the account right now. I contacted the support, but did not get any response yet. I am located in Iceland, if that helps. Anyone else experiencing this as well?

    • Subject: Issue creating temporary mailbox due to OTP verification requirement

      Hello Zoho Mail Support, We are following your recommended approach for email migration and need clarification on how to proceed correctly. Our intended migration approach is: Create a temporary mailbox katja.migration@nellajanuttu.fi Copy all emails

    • The response from the remote server was: 554 5.7.1 : Relay access denied

      Team I am getting the below error when i send email from gmail to my zoho email. I am receiving few emails from other domains. Can you please verify attached config and let me know how to fix this issue ?

    • Zoho mail not working from yesterday

      Zoho mail for server ninjamedia.in not working from yesterday. Please look into it. Error

    • First Response Time, Where to find?

      Hi Currently I'm building a feeder file that auto-fetch ticket details when created/updated. On my table headers, apart from custom fields, I'm specifically looking for First response time. Currently I'm checking capabilities using Zoho Flow but couldn't

    • Issue with Zoho Emails Going to Spam Despite Verified DNS Records

      Dear Zoho Support Team, I am writing to report an issue with my Zoho email account. All emails sent from my domain are consistently being delivered to recipients' spam folders, even though all required DNS records have been correctly configured and verified.

    • Delink of mail id from one auth

      Hi , Please help me to do delink my email id from one auth , the phone is not supporting the higher version i would like to have options with ease process Please help and unable to view the inbox due to the same issues Regards Rekha

    • Outgoing blocked for almost a week – ticket #2472334 – no response yet

      Hi, My Zoho Mail account has been blocked for outgoing messages due to “unusual activity.” The reason is that I forwarded all of the messages from my website contact form (95% spam) from my ZOHO to my personal Gmail. I submitted a support request (Ticket

    • Límite archivo adjunto

      Buenos días Actualmente tengo el plan mail lite, 7 usuarios de 10gb de almacenamiento para correos, quisiera saber cuáles son los límites para adjuntar un archivo adjunto, exceptuando la opción de archivo pesado, ya que últimamente tengo problemas para

    • Lead Email Mandatory in “Add Lead to Journey” Action

      We are currently using the Zoho Marketing Automation Add lead to journey action inside Zoho Flow. We noticed that the field “Lead email address” is mandatory when adding a lead to a journey. Our concern is: Many of our CRM leads do not have an email address.

    • How to prevent users from switching price lists in an order?

      Hi, I have Zoho Finance integrated with Zoho CRM. My team will be placing orders through the CRM using the Finance module. When creating a new customer I will assign it a price list, I don't want the sales rep to switch to a different Price List, other

    • Undelivered Mail uncategorized-bounce errors when sending invoices

      Recently we have been getting Undelivered Mail bounce notification when sending invoices. Reason: uncategorized-bounce Some go through no problem some bounce back. We recently sent 10 invoices, 6 received bounce notifications. After reaching out to the

    • Unable to activate orphaned accounts on a existing domain.

      When I attempt to tag this customer through the partner portal, the Check Availability step first indicates the email is available, but on submission returns this error: "This user does not have account in this service or this user is not an admin. Please

    • Ability to Edit the "Current Job Title" dropdown field

      Current experience/Issue: When a user (candidate) uploads resume to Zoho Recruit candidate portal, some fields are prefilled with the info from the resume/cv correctly. However, we've observed that; 1. the "Current Job Title" dropdown field is usually

    • Unable to Add Users - Zoho Mail Restriction

      I am trying to add new users to my Zoho Mail organization, but I am getting the error: "This user is not allowed to add." We are a legitimate business using Zoho Mail for email hosting only. Our company is based in Saudi Arabia, and we may be accessing

    • Bigin Forms Enhancement: Acknowledge visitors via WhatsApp

      Greetings, We hope all of you are doing well! We're excited to share a new enhancement to Bigin's forms. Let's take a look at it in detail. Acknowledge visitors via WhatsApp The Acknowledge Visitor option in Bigin Forms means visitors receive an instant

    • Integrate your Outlook/ Office 365 inbox with Zoho CRM via Graph API

      Hello folks, In addition to the existing IMAP and POP options, you can now integrate your Outlook/Office 365 inbox with Zoho CRM via Graph API. Why did we add this option? Microsoft Graph API offers a single endpoint to access data from across Microsoft’s

    • No Ability to Rename Record Template PDFs in SendMail Task

      As highlighted previously in this post, we still have to deal with the limitation of not being able to rename a record template when sent as a PDF using the SendMail Task. This creates unnecessary complexity for what should be a simple operation, and

    • Zoho Customer Grievance Escalations Matrix

      We have been with Zoho for little over a 24 months having several licenses for Zoho One and with standalone license for Zoho Commerce Advanced Plan along with their so called "Premium Support" for which they charge you a pretty hefty amount. It's been

    • Data entry and automatic barcode sticker printing

      Hello there I am very new to Zoho.. and not sure if it can do, or should I say, I can easily set it up to do, or first basic requirement. We take in up to 1000 unique used products every week. They come from up to 50 regular suppliers. The are used household appliances. We try to fix most of them. For waste regulation purposes we have to track every machine from the source/supplier it cam from to if it was repaired and put back on the market? or stripped and scrap for material recovery. Is it possible

    • Inventory Barcode Creation - Add Picture of Item

      Hi I am trying to set up bar code labels and include a picture of the item on the label - any idea on how to add that field to the barcode generator?

    • Setting up a barcode system with Zoho Creator

      Hello! I am researching how to set up a barcode inventory system that is compatible with Zoho Creator. I am working with an art inventory, and I want to be able to refer to each piece of artwork with a barcode. My goal is to be able to generate a barcode, store that barcode in a Zoho Creator database, be able to print out a barcode label from that database, and have the database pull up a record when the barcode associated with that record is scanned. I understand that there are barcode generating

    • New Built In QR/Barcode Generator Print Settings

      I'm trying out the new QR/Barcode generator field in Creator. I would think most people will want to print these, like I do. I am not seeing any way to control the height or width of the barcode for printing (inside the print/pdf template builder). The

    • Inventory SKU barcode printing

      Hi I am a developer and am wondering if zoho creator or even zoho inventory have the capability to print barcodes upon submitting a form. I have been researching the forums and have not been able to find any way to do this natively in Zoho. Can someone

    • PRODUCT LABEL MUST HAVE MORE FIELDS AND OPTIONS - VOTE NOW!

      The Zoho Inventory Product Barcode generator is unfinished, very limited, and unusable for most companies that need to generate informative product labels. Companies must be able to generate labels for products they receive to control inventory, so the

    • Ability to "Add Additional Guest" to Bookings

      When using other calendar booking services such as Calendly, there is an option to "Add Additional Guest" to a booking. For example, imagine User A is making a booking on my company's booking calendar and would like to invite their spouse (User B) to

    • Modify logo on exported PDF article

      Hello, I have to 2 Help Center with 2 different brands. If I try to download an article from Help Center Brand #2 as a PDF file, I see the Brand #1 logo on it. Is there a way to modify or hide the logo in the pdf? Thank you Antonio

    • Get Files Associated to Data Template via API

      I have a data template with multiple files associated to it, and trying to write a Deluge script that will fetch files associated with this data template. I created the script below based on the WorkDrive API documentation, one request uses the data templates

    • Pasting Images in Zoho Desk ignores cursor location

      My team has reported an issue which started recently where when we paste an image into a new or existing reply or comment, the pasted image seems to ignore the current cursor location instead paste itself at the last character present in the reply/comment,

    • Push conversation to operator in guided conversations

      I really would like to push the conversation to an operator from a specific deppartment in guided conversations, just like Zobot in sales iq. It would help a lot. For me it does not make sense to use sales iq for messenger, instagram and others, because

    • Next Page