Skip to main content

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.

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 TypeRetry?Reason
400 Bad Request NoThe request is malformed — must be fixed
401 Unauthorized NoInvalid or expired credentials
403 Forbidden NoMissing permissions
404 Not Found NoItem or endpoint doesn’t exist
408 Request Timeout Yes (1–2 retries)Temporary timeout
429 Too Many Requests After delayHit 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: **
SituationGood ResponseAvoid
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.