ToolYour API Errors and Rate Limits

Integrating APIs into production systems demands robust error handling. Without it, your applications can experience unexpected downtime, data inconsistencies, or failed processes. When you build with ToolYour, understanding how our REST API and Model Context Protocol (MCP) respond to issues – particularly concerning API rate limits ToolYour enforces – is critical for maintaining stable and reliable operations.

This guide provides engineers with the essential knowledge to anticipate, diagnose, and resolve common API errors and gracefully manage ToolYour's quota and rate limits. We'll cover typical HTTP status codes, outline effective retry strategies, and highlight how to monitor your usage to prevent interruptions. By integrating these practices, you can ensure your ToolYour integrations run smoothly, even under peak loads.

Authentication errors

One of the most frequent hurdles developers encounter is related to authentication. If your API requests are consistently failing with a 401 Unauthorized status code, it typically indicates an issue with your API key.

Common causes for 401 Unauthorized

• Missing API Key: Your request is not including the X-Api-Key header.
• Invalid API Key: The API key provided in the X-Api-Key header is incorrect, expired, or revoked.
• Incorrect Key Format: The API key might not start with the expected ty_ prefix, or it could contain typos.

How to resolve authentication errors

Always ensure your ToolYour API key is correctly included in the X-Api-Key header for every REST API call. For example, when calling a REST endpoint like /api/v1/documents/docx-to-pdf:

POST https://api.toolyour.com/api/v1/documents/docx-to-pdf
X-Api-Key: ty_YOUR_API_KEY_HERE
Content-Type: application/json

{
  "source_url": "`https://yoursite.com/report.docx`"
}

If you're using ToolYour via the Model Context Protocol (MCP), your client setup will similarly require the API key. While a full MCP client configuration goes beyond the scope of this post, it involves providing your X-Api-Key for authentication. You can find detailed client setup instructions on our ToolYour MCP developer page.

Remember that all API keys associated with a single ToolYour account share the same monthly credit quota. If you have multiple keys, ensure they are active and correct. You can manage and generate new API keys from your ToolYour Dashboard API Keys page. For more details on API key management, refer to our account and keys documentation.

Quota and rate limit responses

When your applications integrate with ToolYour, understanding and managing API rate limits ToolYour imposes is crucial for predictable performance. Hitting these limits results in 429 Too Many Requests status codes, signaling that you've temporarily exceeded your allocated usage.

ToolYour enforces two primary types of limits:

1. Monthly Credit Quota: This is the total number of credits your account can consume within a calendar month.

2. Rolling Throughput Limit: This restricts the number of successful tool runs within a short, rolling time window.

Crucially, both the REST API and MCP usage contribute to the same shared quota for your account.

Understanding the 429 Too Many Requests status code

A 429 Too Many Requests response indicates that your application has exceeded one of the following limits:

Monthly Credit Quota Exceeded

• Credit Consumption: Each successful tool call, whether via REST or MCP, consumes between 1 and 10 credits, depending on the complexity of the tool. Actions like browsing the tool catalog in MCP, using plan_task, or receiving suggestions (status: suggest) without execution are free and do not consume credits. Only actual tool executions, such as solve_task or invoking a REST endpoint like POST https://api.toolyour.com/api/v1/text-utilities/convert-to-slug, consume credits.
• Quota Details:
  • Free plan: Includes 500 credits per month.
  • Pro plan: Offers 20,000 credits per month.
  • Business plan: Provides 100,000 credits per month.
• Reset: Your monthly credit quota resets automatically on the 1st of each calendar month.
• No Overage: ToolYour does not offer pay-as-you-go overage billing. If you hit your monthly credit limit, further requests will be blocked with a 429 until your quota resets or you upgrade your plan. Invalid requests that do not successfully execute a tool generally do not consume credits.

Rolling Throughput Limit Exceeded (Free Plan Specific)

• Free Plan Specific: In addition to the monthly credit quota, the Free plan also has a throughput limit of 5 successful tool runs per rolling 60-second window. This ensures fair usage and prevents abuse of the free tier. Paid plans offer significantly higher or practically unlimited throughput, designed for production workloads.

How to address quota and rate limits

When you receive a 429 Too Many Requests response, consider the following actions:

1. Check response headers: Look for a Retry-After header. This header indicates how many seconds you should wait before making another request. Always respect this header when present.

2. Monitor your usage: Regularly check your usage on the ToolYour Dashboard to track your credit consumption and identify potential bottlenecks before they lead to 429 errors.

3. Upgrade your plan: If you consistently hit your monthly credit quota or require higher throughput, upgrading to a Pro or Business plan is the most direct solution. These plans offer substantially higher credit allocations and throughput for production-grade integrations.

4. Implement retry logic: For transient 429 errors or when a Retry-After header isn't provided, implementing an exponential backoff strategy (discussed in the next section) is crucial.

5. Optimize your calls: Evaluate your application's logic. Are you making unnecessary calls? Can you batch requests or cache results where appropriate to reduce overall API traffic?

Understanding these limits and actively managing your usage will help your integrations perform reliably and avoid unexpected service interruptions. For a comprehensive overview of usage and plans, consult our developer documentation.

Retry strategies

Implementing a robust retry strategy is a cornerstone of resilient production integrations. Not all errors are permanent; some are transient and can be resolved by simply retrying the request after a short delay.

When to retry

You should generally implement retry logic for the following HTTP status codes:

• 429 Too Many Requests: As discussed, this indicates a temporary rate limit or quota exceedance. Always respect the Retry-After header if provided.
• 5xx Server Errors (e.g., 500 Internal Server Error, 503 Service Unavailable): These typically signify temporary issues on the ToolYour server side. Retrying these requests after a delay often succeeds.

When NOT to retry

Certain error codes indicate permanent client-side issues that will not resolve with a retry. Retrying these requests wastes resources and can exacerbate problems:

• 400 Bad Request: Your request body or parameters are malformed. Fix the request before retrying.
• 401 Unauthorized: Authentication failed. Check your API key.
• 403 Forbidden: You lack permission to access the resource.
• 404 Not Found: The requested resource or endpoint does not exist.
• 408 Request Timeout: While this can be transient, it often points to network or client configuration issues. Consider reviewing your timeout settings before retrying blindly.

Recommended retry strategy: Exponential backoff with jitter

The most effective retry strategy is exponential backoff with jitter. This approach combines increasing delays between retries with a random component to prevent a "thundering herd" problem where many clients simultaneously retry at the exact same interval, potentially overwhelming the server further.

1. Initial Delay: Start with a small initial delay (e.g., 100ms or 200ms).

2. Exponential Backoff: Double the delay after each failed attempt.

3. Jitter: Add a random amount of time (jitter) to the calculated delay. This can be a random fraction of the current delay or a fixed random value. For example, (2^n * base_delay) + random_jitter.

4. Maximum Retries: Define a maximum number of retry attempts (e.g., 3-5 times) to prevent indefinite looping in case of persistent errors.

5. Maximum Delay: Cap the maximum delay to avoid excessively long waits for very persistent issues.

Example pseudo-code for retry logic:

import time
import random

MAX_RETRIES = 5
BASE_DELAY_MS = 200

# milliseconds
MAX_DELAY_SECONDS = 30

# seconds

def call_toolyour_api(endpoint, payload, api_key):
    for attempt in range(MAX_RETRIES):
        try:

# Make API request (e.g., using requests library)

# headers = {"X-Api-Key": api_key, "Content-Type": "application/json"}

# response = requests.post(f"https://api.toolyour.com/api/v1/{endpoint}", headers=headers, json=payload)
            response_status_code = random.choice([200, 429, 500])

# Simulate API response
            response_retry_after = 5 if response_status_code == 429 else None

# Simulate Retry-After header

            if response_status_code == 200:
                print(f"Attempt {attempt + 1}: Success!")
                return "Tool output data"

# Return actual data
            elif response_status_code == 429 or response_status_code >= 500:
                print(f"Attempt {attempt + 1}: Received {response_status_code}. Retrying...")

# Check for Retry-After header
                if response_retry_after:
                    wait_time = response_retry_after
                else:

# Exponential backoff with jitter

# Calculate base delay: 2^attempt * BASE_DELAY_MS
                    base_delay = (2 ** attempt) * (BASE_DELAY_MS / 1000)

# Convert to seconds
                    jitter = random.uniform(0, base_delay * 0.2)

# Add 0-20% jitter
                    wait_time = min(base_delay + jitter, MAX_DELAY_SECONDS)
                
                print(f"Waiting for {wait_time:.2f} seconds...")
                time.sleep(wait_time)
            else:

# Non-retryable error
                print(f"Attempt {attempt + 1}: Received {response_status_code}. Non-retryable error.")
                raise Exception(f"API Error: {response_status_code}")

        except Exception as e:
            print(f"An error occurred: {e}")
            if attempt == MAX_RETRIES - 1:
                raise

# Re-raise after final attempt

# For network errors, etc., you might also want to retry

# For simplicity, this example focuses on HTTP status codes
    
    print("Max retries reached. API call failed.")
    raise Exception("API call failed after multiple retries.")

# Example usage (simulated)

# try:

#     result = call_toolyour_api("documents/docx-to-pdf", {"source_url": "`https://example.com/doc.docx`"}, "ty_YOUR_KEY")

#     print(f"Final result: {result}")

# except Exception as e:

#     print(f"Application failed: {e}")

This strategy ensures your application is resilient to transient issues, gracefully handles temporary API rate limits ToolYour imposes, and doesn't get stuck in unproductive retry loops for permanent errors. For further details on specific error codes, refer to our dedicated error documentation.

Monitoring usage

Proactive monitoring of your ToolYour API usage is essential for preventing unexpected service disruptions, especially in production environments. By regularly tracking your credit consumption and request patterns, you can anticipate when you might approach your plan limits and take corrective action before 429 Too Many Requests errors impact your users.

The ToolYour Dashboard

Your primary resource for monitoring usage is the ToolYour Dashboard. Here, you can:

• View Current Credit Usage: See how many credits your account has consumed in the current calendar month against your plan's total allocation.
• Track Request Activity: Gain insights into the volume and success rate of your API calls.
• Review Plan Details: Confirm your current plan (Free, Pro, Business) and its associated credit and throughput limits.

Regularly checking this dashboard allows you to understand your consumption trends and helps in making informed decisions about scaling your integration.

Setting up external alerts

While the ToolYour Dashboard provides a clear overview, for mission-critical applications, you'll want to integrate usage monitoring into your existing operational alerting systems. Although ToolYour does not provide built-in usage alerts directly, you can achieve this by:

1. Estimating Consumption: Based on your application's expected workload and the credit cost of the tools you use (1-10 credits per successful call), you can project your monthly credit consumption.

2. Implementing Application-Level Monitoring: Instrument your application to log successful ToolYour API calls and their estimated credit consumption.

3. Configuring Threshold Alerts: Use your preferred monitoring solution (e.g., Prometheus, Datadog, Splunk) to set alerts based on these logged metrics. For instance, you could trigger an alert when your application's estimated credit usage reaches 75% or 90% of your monthly plan limit. This gives you ample time to react.

Forecasting and capacity planning

Analyzing historical usage data from your monitoring systems allows you to:

• Forecast Future Needs: Identify peak usage times and anticipate future credit requirements based on business growth or seasonal demand.
• Plan Upgrades: If your forecasts indicate you'll regularly exceed your current plan's limits, it's time to consider upgrading. For example, if you find your Free plan's 500 credits or 5 successful tool runs per rolling 60 seconds are no longer sufficient, stepping up to a Pro plan with 20,000 credits or a Business plan with 100,000 credits can prevent future interruptions.
• Optimize Tool Usage: Use data to identify where credits are being consumed and explore if there are opportunities to optimize your application's interaction with ToolYour tools, perhaps by batching requests or only calling tools when strictly necessary.

By actively monitoring and planning, you can ensure your ToolYour integration scales smoothly with your application's demands, maintaining continuous service availability and avoiding unexpected 429 errors due to exhausted quotas.

FAQ

Here are answers to common questions about ToolYour API errors and rate limits:

Q: What HTTP status codes should I expect for rate limit errors?

A: You should expect a 429 Too Many Requests status code when your application hits a rate limit or exceeds your monthly credit quota.

Q: Do invalid API requests count towards my monthly credit quota?

A: Generally, no. Only successful tool calls that complete execution consume credits. Invalid requests, such as those with malformed payloads or incorrect authentication, typically do not consume credits.

Q: When does my ToolYour monthly credit quota reset?

A: Your monthly credit quota resets on the 1st of each calendar month.

Q: I'm on the Free plan and hitting limits. Can I get more credits for free?

A: The Free plan offers 500 credits per month and 5 successful tool runs per rolling 60-second window. To increase your credit allocation and throughput, you will need to upgrade to a paid plan like Pro or Business, which offer significantly higher limits.

Q: What is the throughput limit for the Free plan?

A: The Free plan allows for 5 successful tool runs per rolling 60-second window. This limit is separate from, but in addition to, the monthly credit quota.

Q: Are API keys tied to specific quotas?

A: No, all API keys associated with a single ToolYour account share the same monthly credit quota and throughput limits. If you generate multiple keys, they all draw from the same pool.

Q: Does usage of the Model Context Protocol (MCP) count towards the same quota as the REST API?

A: Yes, both REST API calls and tool executions via MCP (solve_task, run_playbook) consume credits from the same shared monthly quota. However, exploring the MCP catalog, using plan_task, or receiving status: suggest responses without execution are free.

Q: What should I do if I keep getting 401 Unauthorized errors?

A: Check that your API key is correctly included in the X-Api-Key header of your requests and that the key itself is valid and active. Ensure it begins with the ty_ prefix. You can manage your API keys on the ToolYour Dashboard.

Q: Does ToolYour offer pay-as-you-go billing if I exceed my plan's credit limit?

A: No, ToolYour does not offer pay-as-you-go for overage. If you exceed your plan's monthly credit limit, further requests will be blocked with a 429 Too Many Requests error until your quota resets or you upgrade your plan.

Conclusion

Mastering API error handling and understanding API rate limits ToolYour enforces is paramount for building robust and reliable integrations. By recognizing common status codes like 401 Unauthorized and 429 Too Many Requests, and implementing intelligent retry strategies such as exponential backoff with jitter, your applications can gracefully navigate transient issues and ensure continuous operation.

Proactive monitoring of your usage through the ToolYour Dashboard and thoughtful capacity planning are key to staying within your plan limits and scaling your integration effectively. When your needs grow beyond the Free plan's 500 credits per month or its 5 successful tool runs per minute, upgrading to a Pro or Business plan provides the expanded capacity required for production workloads.

For further reading and detailed technical specifications, explore our comprehensive developer resources:

• Review specific error codes and their meanings in our ToolYour Error Documentation.
• Understand plan structures and credit consumption in our Usage and Plans documentation.
• Dive into integrating with the Model Context Protocol (MCP) on the MCP Developer Page.
• Manage your API keys and monitor your account's performance directly from your ToolYour Dashboard.

By diligently applying these practices, you can ensure your ToolYour-powered applications remain stable, efficient, and ready to handle demanding production environments.