This guide is for Cleeng clients integrating with our APIs. It provides clear explanations, common causes, and practical troubleshooting steps for two frequently encountered HTTP errors: 401 Unauthorized and 429 Too Many Requests.
Understanding and resolving these errors will help improve your integration stability and reduce development support inquiries.
How do I resolve a 401 "Unauthorized" error?
What a 401 "Unauthorized" error means
A 401 Unauthorized status code indicates that your API request has not been processed because it lacks valid authentication credentials for the target resource. This means that the API call you are making does not carry sufficient credentials to authorize the action.
Common causes for a 401 "Unauthorized" error
- Missing API Key/Token: The required API key or authentication token is not included in the request headers or body.
- Invalid API Key/Token: The provided API key or token is incorrect, misspelled, or has been revoked.
- Expired Credentials: The authentication token or API key has a limited lifespan and has expired.
- Incorrect Authentication Method: Using the wrong authentication scheme (e.g., trying to use a bearer token when basic authentication is expected, or vice-versa).
- Insufficient Permissions: The API key/token used does not have the necessary permissions to access the requested resource.
Troubleshooting steps
Step | Action |
|---|---|
| Double-check that you are using the correct and current API key or token. |
| Ensure that the authentication header (e.g., Authorization: Bearer YOUR_TOKEN or X-API-KEY: YOUR_KEY) is correctly formatted and present in your API request. |
| If you are using time-limited tokens, check if your token has expired and refresh it as per our API documentation. |
| Refer to the specific Cleeng API endpoint documentation to ensure you are using the correct authentication method for that endpoint. |
Resolution guidance
- Generate a new API key/token from your Cleeng Dashboard if you suspect the current one is compromised or invalid.
- Update your application to correctly include the valid and current authentication credentials in all relevant API calls.
- Implement a token refresh mechanism if your integration relies on short-lived access tokens.
How do I resolve a 429 "Too Many Requests" error?
What a 429 “Too Many Requests” error means
A 429 Too Many Requests status code indicates that the user has sent too many requests in a given amount of time ("throttling"). This is a protective measure to ensure fair usage and system stability.
Common causes for a 429 “Too Many Requests” error
- Exceeding Rate Limits: Your application is sending requests to the Cleeng API faster than the allowed rate limit for your account or the specific endpoint.
- Burst Requests: Sending a large volume of requests in a very short period, even if the average rate over time is within limits.
- Inefficient API Usage: Making redundant or unnecessary API calls.
Troubleshooting steps
Step | Action |
|---|---|
| When you receive a 429 error, the API response usually includes headers like X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Use these headers to understand your limits and when you can retry. |
| Track the number of API requests your application is making over time to identify if it consistently exceeds the allowed limits. |
| Determine which part of your application or workflow is generating a high volume of requests. |
Resolution Guidance
- Implement Exponential Backoff: If you receive a
429error, do not immediately retry the request. Implement an exponential backoff strategy, increasing the delay between retries. Use theRetry-Afterheader if provided in the response. - Batch Requests: Where possible, optimize your application to reduce the number of individual API calls by batching requests or fetching data more efficiently.
- Cache Responses: Cache API responses on your end to avoid repetitive calls for data that doesn't change frequently.
- Distribute Load: If you have multiple processes making API calls, distribute the load to stay within the per-process or per-key limits.
- Contact Support for Higher Limits: If you have a legitimate business need for higher rate limits, contact Cleeng support to discuss your requirements. Provide details on your use case and estimated request volume.
General API Troubleshooting Tips
- Detailed Logging: Ensure your application logs full API request (method, URL, headers, body) and response (status code, headers, body) details. This is invaluable for debugging.
- Error Message Details: Pay close attention to the error messages in the API response body. They often contain specific details about why the request failed.
- Use an API Client/Tool: Use tools like Postman, Insomnia, or curl to manually test API calls and verify your authentication and request structure outside of your application code.
What information should I collect before escalating an issue to Cleeng?
If you have performed the above troubleshooting steps and are still experiencing persistent API errors, please gather the following information before contacting Cleeng Technical Support. This will help us resolve your issue more quickly.
- Exact API Endpoint: The full URL of the API endpoint you are calling (e.g., api.cleeng.com/v2/...).
- HTTP Method: (GET, POST, PUT, DELETE).
- Full Request Headers: Including Authorization (masking the actual token if sharing logs publicly).
- Full Request Body: (if applicable).
- Full Response (Status Code, Headers, Body): The complete response received from the Cleeng API, including the error message.
- Timestamp: The exact date and time (including timezone) of the problematic API calls.
- Your IP Address: The IP address from which your API calls are originating.
- Troubleshooting Steps Taken: A detailed list of the steps you have already performed.