API Errors

All Simple Agent API errors follow the same JSON format to make error handling straightforward in your code.

Standard format

{
  "error": {
    "code": "agent_not_found",
    "message": "Agent with ID 'ag_xyz' was not found or you don't have access.",
    "status": 404,
    "request_id": "req_01hwxyz..."
  }
}

Field	Description
code	Machine-readable identifier — use this for conditional logic
message	Human-readable description of the error
status	HTTP status code
request_id	Unique request ID — include when contacting support

---

HTTP codes

Status	When it occurs
400	Malformed request — missing or invalid parameter
401	Token missing or invalid
403	Valid token but no permission for this resource
404	Resource not found
409	Conflict — e.g., duplicate agent name
422	Invalid entity — valid data but semantically incorrect
429	Rate limit reached
500	Internal error — report with request_id
503	Service temporarily unavailable

---

Common error codes

Authentication

Code	Cause	Solution
missing_auth_header	Authorization header missing	Add Authorization: Bearer af_live_xxx
invalid_token	Malformed token	Check for extra spaces or characters
token_expired	Token expired	Generate a new token in Settings → API
insufficient_scope	Token missing the required scope	Create a new token with the correct scope

Agents

Code	Cause	Solution
agent_not_found	Invalid ID or no access	Confirm the ID in the dashboard
agent_limit_reached	Plan's agent limit reached	Upgrade or delete an inactive agent
agent_name_taken	Name already exists in your account	Use a different name

Sources

Code	Cause	Solution
source_not_found	Source doesn't exist	Confirm the ID
url_not_accessible	URL blocked the crawler	Check robots.txt or add as text
pdf_too_large	PDF > 50MB	Compress or split the file
pdf_encrypted	Password-protected PDF with no password provided	Include the password field at upload
indexing_in_progress	Re-indexing in progress	Wait and check the source status

Chat

Code	Cause	Solution
message_limit_reached	Monthly message quota exhausted	Wait for renewal or upgrade
context_too_long	Conversation too long for the model	Restart the conversation or reduce history
llm_timeout	LLM didn't respond within 30s	Retry — rarely occurs during peak times

---

Recommended error handling

async function apiRequest(url: string, options: RequestInit) {
  const res = await fetch(url, options);

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

    switch (error.error.code) {
      case "rate_limit_exceeded":
        // Wait and retry
        await sleep(error.error.retry_after * 1000);
        return apiRequest(url, options);

      case "token_expired":
        // Redirect to token renewal
        throw new AuthError("Token expired. Generate a new one in Settings → API.");

      case "message_limit_reached":
        // Notify user
        throw new QuotaError("Monthly message limit reached.");

      default:
        // Log with request_id for debugging
        console.error(`API Error [${error.error.request_id}]:`, error.error.message);
        throw new Error(error.error.message);
    }
  }

  return res.json();
}

---

500 errors — what to do

500 errors are rare and usually transient. If they persist for more than 5 minutes:

1. Check the platform status page
2. Try to reproduce with curl to isolate the issue
3. Open a ticket at support@simple-agent.me including the request_id

---

Status page

Monitor real-time status at status.simple-agent.me. You can subscribe to email or webhook notifications for incidents.

Rate Limits → · Authentication → · Webhooks →