> ## Documentation Index
> Fetch the complete documentation index at: https://watermelon.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Error Handling, Timeouts, Retries
> This guide explains how to design and handle errors, timeouts and retries when building Actions in Watermelon, so your AI Agent behaves safely in production.
When an Action goes live, you want predictable, stable behavior — even when APIs fail, slow down, or respond with unexpected results.
## **How the AI Agent Surfaces API Failures to Users**
The AI Agent doesn’t display raw error codes to end users. Instead, it interprets the failure and responds with natural fallback text based on your Domain Knowledge and Action configuration.
### **Developer Behavior**
* In chat, the Agent **never exposes the error code or raw API message**.
* You can guide how it responds by adding fallback instructions.
**Example fallback instruction (Domain Knowledge):**
> “If the Action fails, tell the user that their request couldn’t be completed right now and to try again later.”
**Good example response to user:**
> “Sorry, I wasn’t able to reach the system right now. Could you try again in a few minutes?”
## **Timeouts & Slow APIs**
Each Action call has an execution timeout managed by the Watermelon platform. If your API is slow or unresponsive, the request will fail.
### **Best Practices**
* Ensure your API endpoint responds within **1 - 2 seconds** for optimal conversational flow.
* API with **latency > 3 seconds** will timeout automatically no retry
* If your API supports asynchronous operations, handle long-running tasks outside of the Action.
* Always test API latency before going live.
Use your health check endpoint to detect degraded performance early.
## **When to Retry vs. Fail Fast**
Retries can help recover from temporary errors (like network blips), but overusing them can overload your API or frustrate users.
| **Error Type** | **Retry?** | **Reason** |
| :------------------------ | :-------------------------------------------------------------- | :--------------------------------------- |
| **400 Bad Request** | No | The request is malformed — must be fixed |
| **401 Unauthorized** | No | Invalid or expired credentials |
| **403 Forbidden** | No | Missing permissions |
| **404 Not Found** | No | Item or endpoint doesn’t exist |
| **408 Request Timeout** | Yes (1–2 retries) | Temporary timeout |
| **429 Too Many Requests** | After delay | Hit rate limit — backoff required |
| **500 / 502 / 503 / 504** | Yes (with backoff) | Temporary server or network issue |
### **Backoff Example**
When retrying 429 or 5xx errors:
* Wait 1s → retry 1
* Wait 3s → retry
* Stop after 3 attempts
Watermelon doesn’t auto-retry Actions. You must handle retries within your API, or build retry logic on your server.
## **Handling 429 Rate Limits Gracefully**
APIs use **HTTP 429** to signal too many requests. If your Action triggers this, slow down requests and communicate clearly.
### **Developer Recommendations**
* Check the API’s **rate limit headers**, often included as:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709910285
```
* Respect the cooldown period before retrying.
* Avoid triggering Actions in rapid succession in testing environments.
### **Example user-facing fallback**
> “Looks like the system is busy right now. I’ll try again shortly.”
## **Writing Safe Error Copy**
Keep user-facing responses clear, polite, and generic. Never expose internal details, IDs, or stack traces.
\*\*Examples: \*\*
| **Situation** | **Good Response** | **Avoid** |
| :------------ | :----------------------------------------------------- | :----------------------------------- |
| API down | “I can’t connect right now. Please try again later.” | “500 Internal Server Error” |
| Invalid input | “That number doesn’t seem valid — could you check it?” | “400 Bad Request: missing parameter” |
| Auth issue | “I can’t access that system right now.” | “401 Unauthorized: Token invalid” |
Keep technical information inside the **Playground** or developer logs only.
## **Provider-Side Rate Limits & Backoff**
Every API defines its own rate limits — know them before you deploy.
### **Developer Checklist**
* Check the API’s documentation for:
* Allowed requests per minute/hour/day
* Whether rate limits reset automatically
* If they differ by endpoint or authentication type
* Apply **client-side throttling** in your middleware or integration layer if your usage is high.
* Implement **exponential backoff** to avoid bans:
```
wait = base_delay * (2 ^ retry_count)
```
Example: 1s → 2s → 4s → 8s, stop after 4 tries.