Errors AI Tools

Open in ChatGPT

Open in ChatGPT to ask questions about this page

Open in Claude

Open in Claude to ask questions about this page

Copy as Markdown

Copy this page as markdown to use with AI assistants

View as Markdown

Open this page as markdown in a new tab

The Zoho Cliq REST API uses standard HTTP status codes to communicate the success or failure of API requests. Understanding these status codes is essential for building robust integrations that can gracefully handle errors and provide meaningful feedback to users.

Status codes in the 2xx range indicate successful operations, codes in the 4xx range signal client-side errors (such as invalid requests or authentication failures), and codes in the 5xx range represent server-side errors.

Additionally, each endpoint may return endpoint-specific error codes, which are listed under the respective endpoint's description in a tabular format.

Status Code	Description
200	OKThe request was successfully completed. The response body contains the requested resource data.
201	CreatedThe request succeeded and one or more resources have been created (e.g., new channel, message, or bot).
204	No ContentThe request was successful but there is no content to return (common for DELETE operations).
400	Bad RequestThe request cannot be processed due to malformed syntax, invalid parameters, or missing required fields. Verify your request payload and parameters.
401	UnauthorizedAuthentication failed or was not provided. This typically occurs when the OAuth token is invalid, expired, or missing from the Authorization header.
403	ForbiddenThe authenticated user lacks sufficient permissions to access the requested resource. Verify that your OAuth scopes include the necessary permissions for this operation.
404	Not FoundThe requested resource does not exist or the URL is incorrect. Check the resource ID and endpoint path for accuracy.
405	Method Not AllowedThe HTTP method used is not supported for this endpoint. For example, using PUT when only GET and POST are allowed.
406	Not AcceptableThe server cannot produce a response matching the acceptable values defined in the request headers.
409	ConflictThe request conflicts with the current state of the resource (e.g., attempting to create a duplicate resource).
429	Too Many RequestsRate limit exceeded. You've sent too many requests within a specific time window. Implement exponential backoff and retry logic.
500	Internal Server ErrorThe Zoho Cliq server encountered an unexpected error. If this persists, contact support@zohocliq.com with your request details.
502	Bad GatewayThe server received an invalid response from an upstream server. This is usually temporary; retry with exponential backoff.
503	Service UnavailableThe server is temporarily unable to handle the request due to maintenance or overload. Retry after a delay.
504	Gateway TimeoutThe server did not receive a timely response from an upstream server. Consider reducing request complexity or retrying.


$ curl -X GET "https://cliq.zoho.com/api/v2/chats" \
  -H "Authorization: Zoho-oauthtoken 1000.xxxxxxxxxxxxxxxxxxxxx"


{
  "chats": [
    {
      "id": "CT_1234567890_123456",
      "name": "John Doe",
      "type": "personal",
      "last_modified_time": "2026-04-15T10:30:00Z",
      "unread_count": 3
    }
  ]
}


{
  "message": "The request cannot be performed. Usually because of malformed parameter or missing parameter."
}


{
  "message": "Request was rejected because of invalid AuthToken."
}


{
  "message": "The user does not have enough permission or possibly not an user of the respective organization to access the resource."
}


{
  "message": "The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL."
}


{
  "message": "Too many requests within a certain time frame."
}


{
  "message": "Cliq server encountered an error which prevents it from fulfilling the request."
}

Error Response Structure

When an API request fails, the Zoho Cliq API returns a structured error response in JSON format. Understanding the error response structure helps you build intelligent error handling mechanisms in your application.

Common Error Response Fields

Field	Type	Description
`message`	String	A human-readable description of the error that occurred
`error`	String	A brief error identifier or category (optional, varies by endpoint)
`details`	Object/Array	Additional context about the error, such as invalid field names (optional)

Common Error Scenarios

Below are common error scenarios you may encounter when working with the Zoho Cliq API, along with recommended solutions:

🔐 Authentication Errors (401)

Invalid OAuth Token: Ensure you're passing the token in the format Authorization: Zoho-oauthtoken YOUR_TOKEN
Expired Token: Access tokens expire after 1 hour. Use your refresh token to generate a new access token
Revoked Token: The token may have been revoked. Re-authenticate the user to obtain a new token

🚫 Permission Errors (403)

Insufficient Scopes: Verify that your OAuth application has been granted the required scopes for the operation
Resource Access: Confirm the authenticated user has access to the requested channel, chat, or resource
Organizational Restrictions: Some operations may be restricted by organizational policies or admin settings

❌ Validation Errors (400)

Missing Required Fields: Check the API documentation for required parameters and include them in your request
Invalid Data Types: Ensure field values match expected types (string, integer, boolean, etc.)
Invalid Format: Validate data formats for fields like dates, emails, or IDs
Constraint Violations: Respect field length limits, allowed values, and other constraints

⏱️ Rate Limiting (429)

Threshold Limits: Most Zoho Cliq APIs have rate limits of 15-20 requests per minute per user
Lock Period: When rate limited, you must wait for the lock period (typically 10 minutes) before making new requests
Best Practice: Implement exponential backoff and request queuing to stay within rate limits
Monitoring: Track your API usage patterns and optimize request frequency

Error Handling Best Practices

Implementing robust error handling is crucial for building reliable integrations with the Zoho Cliq API. Follow these industry best practices to create resilient applications that gracefully handle failures.

🔄 Retry Logic

Implement intelligent retry mechanisms for transient errors:

Retry on 5xx Errors: Server errors (500, 502, 503, 504) are often temporary. Implement automatic retries with exponential backoff
Exponential Backoff: Use increasing delays between retries (e.g., 1s, 2s, 4s, 8s) to avoid overwhelming the server
Maximum Attempts: Set a reasonable limit (e.g., 3-5 attempts) to prevent infinite retry loops
Don't Retry 4xx Errors: Client errors typically require fixing the request, not retrying
Jitter: Add random variation to retry delays to prevent thundering herd problems

📊 Logging and Monitoring

Log All Errors: Capture full error responses including status code, message, and request context
Include Request IDs: Log request identifiers to help track specific API calls during troubleshooting
Monitor Error Rates: Track error frequency and types to identify systematic issues
Alert on Patterns: Set up alerts for unusual error spikes or persistent failures
Don't Log Tokens: Never log OAuth tokens or other sensitive authentication credentials

💡 User Experience

User-Friendly Messages: Translate technical error messages into clear, actionable user guidance
Contextual Help: Provide specific instructions based on the error type (e.g., "Please check your permissions")
Graceful Degradation: When possible, provide partial functionality even if some API calls fail
Loading States: Show appropriate loading indicators during API requests
Error Recovery: Offer clear paths for users to recover from errors (e.g., retry buttons, help links)

🔒 Security Considerations

Sanitize Error Messages: Don't expose sensitive internal details or system information in user-facing errors
Rate Limit Protection: Implement client-side rate limiting to prevent hitting API thresholds
Token Management: Automatically refresh expired tokens before making API calls when possible
Audit Trails: Maintain secure logs of API errors for security auditing and compliance

⚡ Performance Optimization

Circuit Breaker Pattern: Stop making requests temporarily if repeated failures indicate systemic issues
Request Queuing: Queue API requests to stay within rate limits and manage load
Caching: Cache successful responses to reduce API calls and improve resilience
Timeout Configuration: Set appropriate request timeouts (30-60 seconds for most operations)
Fail Fast: Validate requests client-side before making API calls to catch errors early

📝 Example Error Handling Code

Here's a reference implementation of robust error handling with retry logic:


async function makeCliqAPIRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      // Handle successful responses
      if (response.ok) {
        return await response.json();
      }
      
      // Parse error response
      const errorData = await response.json();
      
      // Don't retry client errors (4xx)
      if (response.status >= 400 && response.status < 500) {
        if (response.status === 401) {
          throw new Error('Authentication failed. Please refresh your token.');
        } else if (response.status === 403) {
          throw new Error('Permission denied. Check OAuth scopes.');
        } else if (response.status === 429) {
          throw new Error('Rate limit exceeded. Please wait before retrying.');
        } else {
          throw new Error(errorData.message || 'Request failed');
        }
      }
      
      // Retry server errors (5xx) with exponential backoff
      if (response.status >= 500 && attempt < maxRetries) {
        const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
        const jitter = Math.random() * 1000;
        console.log(`Server error. Retrying in ${delay + jitter}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay + jitter));
        continue;
      }
      
      throw new Error(errorData.message || 'Server error occurred');
      
    } catch (error) {
      if (attempt === maxRetries) {
        console.error('Max retries reached:', error);
        throw error;
      }
    }
  }
}

// Usage example
try {
  const chats = await makeCliqAPIRequest(
    'https://cliq.zoho.com/api/v2/chats',
    {
      headers: {
        'Authorization': 'Zoho-oauthtoken YOUR_TOKEN',
        'Content-Type': 'application/json'
      }
    }
  );
  console.log('Chats retrieved:', chats);
} catch (error) {
  console.error('Failed to retrieve chats:', error.message);
  // Show user-friendly error message
}

Rate Limiting

To ensure fair usage and maintain system stability, the Zoho Cliq API enforces rate limits on API requests. Understanding these limits is essential for designing applications that remain within acceptable usage thresholds.

Rate Limit Structure

Most Zoho Cliq API endpoints implement the following rate limiting structure:

Threshold Limit: Typically 15-20 requests per minute per authenticated user
Lock Period: When the threshold is exceeded, a 10-minute cooldown period is enforced
Per-User Basis: Limits are calculated per authenticated user, not per application
Endpoint Specific: Different endpoints may have different rate limits based on their resource intensity

Rate Limit Response

When you exceed the rate limit, the API returns a 429 Too Many Requests status code:


{
  "message": "Too many requests within a certain time frame."
}

Strategies to Avoid Rate Limiting

Request Throttling: Implement client-side rate limiting to stay well below API thresholds
Batch Operations: When possible, use batch endpoints to process multiple items in a single request
Caching: Cache frequently accessed data to reduce redundant API calls
Webhooks: Use webhooks for real-time notifications instead of polling APIs repeatedly
Pagination: Use appropriate page sizes to avoid making excessive requests for large datasets
Off-Peak Processing: Schedule bulk operations during off-peak hours when rate limits are less likely to be hit
Queue Management: Implement request queues with controlled processing rates

Monitoring Your Usage

Track the number of API requests your application makes per minute
Log 429 responses to identify patterns and adjust your request strategy
Implement dashboard monitoring to visualize API usage trends
Set up alerts when approaching rate limit thresholds
Review API call patterns regularly to optimize efficiency

⚠️ Important: When rate limited, you must wait for the full lock period (typically 10 minutes) before making additional requests. Continued requests during the lock period will extend the lockout duration.

Errors AI Tools Open in ChatGPT Open in ChatGPT to ask questions about this page Open in Claude Open in Claude to ask questions about this page Copy as Markdown Copy this page as markdown to use with AI assistants View as Markdown Open this page as markdown in a new tab