API Error Codes#

All RAGFlow API error codes are defined in the RetCode enum (common/constants.py), an IntEnum with two categories:

• Application-level codes — RAGFlow-specific integers that appear in the JSON body's "code" field.
• HTTP-mirror codes — values that match standard HTTP status codes (400, 401, 403, 404, 409, 500) and are used as both the JSON body code and the HTTP status in some error paths.

Every API response follows the same JSON envelope, built by get_json_result():

{ "code": <RetCode>, "message": "...", "data": null }

The HTTP status code is not always the same as the body code. Application-level errors (codes < 400) are typically returned with HTTP 200; only UNAUTHORIZED (401) and NOT_FOUND (404) are consistently returned with a matching HTTP status.

Full Code Table#

1

401 UNAUTHORIZED vs. 109 AUTHENTICATION_ERROR#

This is the most important semantic distinction in RAGFlow's error model:

How 401 is produced: login_required calls _load_user(). If no credential is resolved, it raises QuartAuthUnauthorized, which is caught by the app-level 401 error handler and returned as an HTTP 401 with code: 401 in the body.

Special case — AUTH_BETA routes: When a route is decorated with @login_required(auth_types=AUTH_BETA) and authentication fails, the decorator returns HTTP 200 with code: 102 (DATA_ERROR) instead of raising a 401 2. This matches the external API convention.

How 109 is produced: After authentication, ownership is verified separately. For chat/session mutation routes (PUT/PATCH/DELETE on /chats/<chat_id> and session sub-routes), _ensure_owned_chat(chat_id) queries DialogService filtering on both tenant_id=current_user.id and id=chat_id. An empty result returns RetCode.AUTHENTICATION_ERROR (109) via get_json_result() with HTTP 200 3.

Key Implementation References#