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 The request is malformed — must be fixed 401 Unauthorized Invalid or expired credentials 403 Forbidden Missing permissions 404 Not Found Item or endpoint doesn’t exist 408 Request Timeout Temporary timeout 429 Too Many Requests Hit rate limit — backoff required 500 / 502 / 503 / 504 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 Interactive Tester 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. 
