Error Codes

This article describes the DolphinX API error code system, helping developers provide more precise messages or recovery strategies at the application layer based on error codes.

1. Error Response Example

{
 "type": "ERROR",
 "msgId": "...",
 "correlationId": "<requestId>",
 "action": "<action>",
 "agentId": "<agentId>",
 "sessionId": "<sessionId>",
 "error": {
 "code": "<BusErrorCode>",
 "message": "<error description>",
 "reason": "<optional, reason for the error>",
 "providerStatus": "<optional, LLM provider HTTP status code>",
 "providerCode": "<optional, LLM provider error code>",
 "retryable": "<optional, true|false>"
 },
 "headers": {
 "busErrorCode": "<BusErrorCode>",
 "httpStatus": "<HTTP status code>",
 "llmProviderStatus": "<optional, LLM provider HTTP status code>",
 "providerCode": "<optional, LLM provider error code>",
 "retryable": "<optional, true|false>"
 }
}

2. Error Code Description


Error Code	HTTP Status Code	Description
BUS_UNAUTHENTICATED	401	The user is not authenticated, or the login session has expired. The client should prompt the user to log in again.
BUS_PERMISSION_DENIED	403	The user is authenticated but does not have permission to perform this operation. The client should not clear the login session.
BUS_UNKNOWN_ACTION	404	Unknown action. The requested endpoint/action name does not exist.
BUS_NOT_FOUND	404	The resource does not exist.
BUS_AGENT_NOT_FOUND	404	The specified agent does not exist or has been deleted.
BUS_SESSION_NOT_FOUND	404	The specified session does not exist.
BUS_CONFLICT	409	Resource state conflict, such as a duplicate creation attempt, a version conflict, or a resource state that does not allow the requested operation.
BUS_QUEUE_FULL	429	The DolphinX API request queue is full, and the server is overloaded. Try again later.
BUS_RATE_LIMITED	429	Rate limited by DolphinX.
BUS_TIMEOUT	504	The DolphinX request timed out during processing.
BUS_NODE_UNREACHABLE	503	In cluster mode, the target node is unreachable, and the request cannot be routed.
BUS_HANDLER_ERROR	500	Internal processor error. See `error.message` in the error response for details.
BUS_LLM_PROVIDER_ERROR	502	The upstream LLM provider returned a 5xx response, the response could not be parsed, or no valid LLM output was returned. The provider's original HTTP status is available in `error.providerStatus` or `headers.llmProviderStatus` in the error response.
BUS_LLM_CONFIG_ERROR	502	The LLM configuration, provider, authentication key, or model is unavailable. Provider 401/403/404 errors fall into this category.
BUS_LLM_QUOTA_EXCEEDED	402	The LLM account balance or token quota is insufficient.
BUS_LLM_RATE_LIMITED	429	The LLM provider rate-limited the request or returned `too many requests`.
BUS_LLM_PROVIDER_TIMEOUT	504	The LLM request timed out, or the provider returned 408/504.
BUS_CONTEXT_LENGTH_EXCEEDED	413	The context window or token limit was exceeded, including `local context budget overrun` and `provider context length` errors.
BUS_STREAM_INTERRUPTED	499	Streaming was interrupted, such as when the SSE connection was disconnected or the LLM streaming response terminated abnormally.
BUS_INVALID_ARGUMENT	400	The request parameters are invalid, such as missing required fields, incorrect types, or values outside the allowed range.
BUS_PAYLOAD_TOO_LARGE	413	The request body or payload exceeds the limit.
REPLACE_REJECTED	409	The workspace.replace request was rejected. See `error.reason` and `error.message` in the error response for details.
WORKSPACE_REJECTED	400	The request was rejected due to workspace state, file constraints, or platform constraints. See error.reason and error.message in the error response for details.
BUS_NOT_STARTED	503	The DolphinX API has not finished initializing, so the service is temporarily unavailable.

LLM provider error responses typically include the following additional fields in error and headers:


Field	Description
providerStatus/llmProviderStatus	The LLM provider's original HTTP status code.
providerCode	The LLM provider's original error code. Returned only when it can be parsed from the response.
retryable	Whether the request can be retried. The value is "true" or "false". BUS_LLM_RATE_LIMITED, BUS_LLM_PROVIDER_TIMEOUT, and BUS_LLM_PROVIDER_ERROR are retryable categories.

For workspace errors, the specific reason is indicated by identifiers in error.reason and error.message in the error response. Common identifiers include:


Identifier	Description
missing_hash	The `replace` request is missing a hash.
stale_file	The hash in the `replace` request does not match the current file hash.
invalid_replacements	replacement is missing, empty, or in an invalid format.
empty_old	replacements[].old is empty.
old_not_found	replacements[].old is not found.
old_not_unique	old appears multiple times when `replaceAll=false`.
invalid_text	The file content or replacement text is not UTF-8.
file_not_found	The file does not exist in the workspace.
quota_exceeded	The total workspace size, individual file size, or file count exceeds the limit.
target_invalid	The target is not a regular file in the workspace.