In the world of API integration, errors are inevitable. Whether it's a validation slip or a rate limit breach, understanding how to read Zoho's error logs is the difference between a broken sync and a seamless workflow.
At Kalki LLP, we build "Error-Resilient" integrations. This guide explains the standard error structure, HTTP status codes, and the specific Zoho-defined error codes you will encounter.
When a request fails, Zoho Books returns a JSON object instead of the requested data. Every error response contains two key fields:
code: A numeric value representing the specific error type.
message: A human-readable description of what went wrong.
Example Error Response:
{
"code": 57,
"message": "Invalid Access Token"
}
Zoho Books uses standard HTTP status codes to indicate the general category of the error:
| Status Code | Meaning | Action for Kalki LLP Developers |
| 200 OK | Success | Request was processed correctly. |
| 201 Created | Success | A new resource (Invoice/Contact) was created. |
| 400 Bad Request | Validation Error | Check your JSON body for missing mandatory fields. |
| 401 Unauthorized | Auth Error | Your Access Token has expired or is invalid. |
| 404 Not Found | URL Error | The resource ID or the API endpoint URL is incorrect. |
| 429 Too Many Requests | Rate Limit | You have exceeded the allowed number of API calls. |
| 500 Internal Error | Server Error | A temporary issue on Zoho’s side. Retry after 5 minutes. |
Beyond HTTP codes, Zoho provides specific internal codes. Here are the ones we most frequently troubleshoot for kalkillp.com clients:
| Code | Message | Resolution |
| 0 | Success | Operation completed successfully. |
| 2 | Invalid ID | The ID provided for the Contact, Invoice, or Item does not exist. |
| 5 | Internal Error | Rare. Contact Zoho Support or retry later. |
| 45 | Request Limit Exceeded | You are hitting more than 100 requests per minute. |
| 57 | Invalid Access Token | Refresh your token using the Refresh Token (Step 4). |
| 6024 | Invalid Organization ID | Check your organization_id parameter in the URL. |
| 1002 | Transaction error | Usually occurs when trying to delete a reconciled transaction. |
When writing scripts in Zoho Books or CRM, never assume a request will succeed. Always wrap your invokeurl in a check:
response = invokeurl
[
url :"https://www.zohoapis.in/books/v3/invoices?organization_id=123456"
type :GET
connection :"kalki_connection"
];
// Check if code is not 0
if(response.get("code") != 0)
{
errorMessage = response.get("message");
info "Kalki Alert: API Call Failed with message: " + errorMessage;
// Log this to a custom 'Audit' module or send an email to admin
}
else
{
info "Data Fetched Successfully!";
}
Zoho Books has strict limits to ensure platform stability.
Minutely Limit: 100 requests per minute.
Daily Limit: Varies by plan (e.g., Professional: 5,000 / Elite: 10,000).
Kalki LLP Pro-Tip: If you are performing a bulk migration (e.g., Tally to Zoho), use a "Sleep" function in your code to pause for 1 second between every few requests to stay under the 100/min threshold.
Before contacting the Kalki LLP support team, run through this 3-point checklist:
Check the Domain: Are you calling .com when your account is in the .in (India) data center?
Check the Header: Is your authorization header formatted exactly as Zoho-oauthtoken {token}?
Check the JSON: Use a JSON validator to ensure your request body doesn't have stray commas or missing brackets.
If you are seeing persistent errors or "Internal Server Errors" that won't go away, our technical team at Kalki LLP can audit your API logs and fix your integration logic.