Skip to main content

Error Response Format

All errors return a JSON object with an error field:
{
  "error": "Error message here",
  "message": "Optional detailed message"
}

HTTP Status Codes

CodeMeaningCommon Causes
400Bad RequestInvalid JSON, missing required fields
401UnauthorizedMissing or invalid API key
403ForbiddenNo active subscription
404Not FoundAgent not found or invalid endpoint
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side issue

Common Errors

Missing API Key

{
  "error": "Missing or invalid API key"
}
Solution: Include your API key in the x-api-key header:
-H "x-api-key: YOUR_API_KEY"

Invalid API Key

{
  "error": "Unauthorized"
}
Solution: Check that your API key is correct and hasn’t been deleted.

No Active Subscription

{
  "error": "Active subscription required"
}
Solution: Subscribe at roselabs.ai.

Agent Not Found

{
  "error": "Agent not found"
}
Solution: Verify the agent ID is correct. Agents may be deleted after completion.

Missing Goal

{
  "error": "goal is required"
}
Solution: Include the goal field in your request body when creating an agent.

Invalid Model

{
  "error": "Invalid model specified"
}
Solution: Use a valid model: rose-1-lite or rose-1-ultra.

Rate Limit Exceeded

{
  "error": "Rate limit exceeded"
}
Solution: Implement exponential backoff and retry logic.

Error Handling Best Practices

Retry with Exponential Backoff

import time
import requests

def create_agent_with_retry(goal, max_retries=3):
    url = "https://navi-j9a9.onrender.com/api/agents"
    headers = {
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY"
    }

    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json={"goal": goal})

        if response.status_code == 429:
            wait_time = (2 ** attempt) + random.random()
            time.sleep(wait_time)
            continue

        if response.status_code >= 500:
            wait_time = (2 ** attempt) + random.random()
            time.sleep(wait_time)
            continue

        return response

    raise Exception("Max retries exceeded")

Handle Specific Error Types

try {
  const response = await fetch("https://navi-j9a9.onrender.com/api/agents", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "YOUR_API_KEY"
    },
    body: JSON.stringify({ goal: "Research AI trends" })
  });

  if (!response.ok) {
    const error = await response.json();

    switch (response.status) {
      case 401:
        throw new Error("Invalid API key. Check your credentials.");
      case 403:
        throw new Error("Subscription required. Visit roselabs.ai to subscribe.");
      case 429:
        throw new Error("Rate limited. Please slow down.");
      default:
        throw new Error(error.message || "Unknown error");
    }
  }

  return await response.json();
} catch (error) {
  console.error("API Error:", error);
  throw error;
}

Getting Help

If you encounter persistent errors:
  1. Check the status page for outages
  2. Review your API key in Settings
  3. Contact support at [email protected]