Skip to main content
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.

​
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:
  • 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: ** 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:
Example: 1s → 2s → 4s → 8s, stop after 4 tries.