Error Codes & Exception Handling

ToolsWallet RAG uses conventional HTTP response codes to indicate the success or failure of an API request. In general: 2xx codes indicate success, 4xx codes indicate an issue with the provided parameters, and 5xx codes indicate a server error.

1. Standard Error Response Schema

All error responses return a standardized JSON structure:

JSON

{
  "success": false,
  "message": "Rate limit exceeded. Maximum 10 requests per minute.",
  "error": "ERR_RATE_LIMIT"
}

2. HTTP Status Codes Table

Here is the complete reference of status codes returned by the API:

Status Code	Error Type	Description & Resolution
200 OK	Success	Request succeeded and grounded response generated.
400 Bad Request	Validation Error	Missing required parameters (`ragId` or `query`).
401 Unauthorized	Authentication Error	Missing or invalid `X-API-Key` or Bearer JWT token.
403 Forbidden	Domain Origin Block	Request Origin is not included in the API Key's domain whitelist.
404 Not Found	Resource Missing	Knowledge Base (RAG ID) does not exist or is inactive.
429 Too Many Requests	Rate Limit Exceeded	Exceeded 10 requests per minute or 100 requests per day.
500 Server Error	Internal Failure	Temporary upstream inference error. Retry with backoff.

3. Handling Rate Limits (429)

When building client applications, implement exponential backoff retry logic when encountering 429 Too Many Requests status codes:

JAVASCRIPT

async function queryWithRetry(url, options, retries = 3, delay = 1000) {
  for (let i = 0; i < retries; i++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;
    // Wait before retrying
    await new Promise((resolve) => setTimeout(resolve, delay * Math.pow(2, i)));
  }
  throw new Error("Rate limit exceeded after max retries.");
}

4. Handling CORS & Origin Errors (403)

If your browser console displays 403 Forbidden: Origin not allowed, go to Dashboard > API Keys tab. Edit your active API Key and add your domain (e.g. https://mywebsite.com or http://localhost:3000) to the Allowed Origins list.

Ready to build your Custom RAG?

Deploy in under 3 minutes with 2 free RAG knowledge bases.

Create Free RAG