ErrorCode

ErrorCode is an enumeration representing error codes returned by QPilot OS operations. These codes indicate the type of failure that occurred during quantum job submission, execution, or result retrieval.

Overview

Error codes help diagnose issues when interacting with the QPilot OS platform. Each code corresponds to a specific category of failure, from database errors to chip offline conditions.

Enum Values

Success

Value	Description
NO_ERROR_FOUND	No error occurred; the operation completed successfully

Data and Format Errors

Value	Description
DATABASE_ERROR	A database operation failed
ORIGINIR_ERROR	The OriginIR program string is invalid or malformed
JSON_FIELD_ERROR	A required JSON field is missing or contains an invalid value
ERR_PARAMETER	Invalid or missing parameter in the request
ERR_TASK_CONFIG	Task configuration is invalid

Backend and Computation Errors

Value	Description
BACKEND_CALC_ERROR	The backend encountered an error during computation
ERR_UNSUPPORT_BACKEND_TYPE	The specified backend type is not supported
ERR_QVM_INIT_FAILED	Quantum virtual machine initialization failed
ERR_QCOMPILER_FAILED	The quantum compiler encountered an error
CLUSTER_SIMULATE_CALC_ERR	Cluster simulation computation failed
CLUSTER_BASE	Base cluster error

Resource Limit Errors

Value	Description
ERR_TASK_BUF_OVERFLOW	Task buffer overflow; too many tasks queued
EXCEED_MAX_QUBIT	The program exceeds the maximum number of qubits supported by the chip
EXCEED_MAX_CLOCK	The program exceeds the maximum circuit depth (clock cycles) allowed
ERR_SUB_GRAPH_OUT_OF_RANGE	The subgraph specification is out of the valid range
ERR_TASK_STATUS_BUF_OVERFLOW	Task status buffer overflow
ERR_QPROG_LENGTH	The quantum program exceeds the maximum allowed length

Circuit and Compilation Errors

Value	Description
ERR_PRE_ESTIMATE	Pre-estimation of circuit resources failed
ERR_MATE_GATE_CONFIG	Mate gate configuration error
ERR_FIDELITY_MATRIX	Fidelity matrix computation error
ERR_QST_PROG	Invalid Quantum State Tomography program
ERR_EMPTY_PROG	The submitted quantum program is empty
ERR_QUBIT_SIZE	Invalid qubit size specification
ERR_QUBIT_TOPO	Qubit topology error
ERR_QUANTUM_CHIP_PROG	Quantum chip program error
ERR_REPEAT_MEASURE	Repeated measurement configuration error
ERR_OPERATOR_DB	Operator database error

Task Management Errors

Value	Description
ERR_UNKNOW_TASK_TYPE	Unknown or unsupported task type
ERR_NOT_FOUND_APP_ID	The specified application ID was not found
ERR_NOT_FOUND_TASK_ID	The specified task ID was not found
ERR_PARSER_SUB_TASK_RESULT	Failed to parse sub-task results
ERR_TASK_TERMINATED	The task was terminated before completion

Network and Connection Errors

Value	Description
ERR_SYS_CALL_TIME_OUT	System call timed out
ERR_INVALID_URL	The provided URL is invalid
ERR_BACKEND_CHIP_TASK_SOCKET_WRONG	Backend chip task socket error
ERR_TCP_INIT_FATLT	TCP initialization failed
ERR_TCP_SERVER_HALT	TCP server is halted or unreachable

Chip Availability

Value	Description
ERR_CHIP_OFFLINE	The target quantum chip is currently offline
ERR_SCHEDULE_CHIP_TOPOLOGY_SUPPORTED	The chip topology is not supported by the scheduler

General

Value	Description
UNDEFINED_ERROR	An undefined or unrecognized error occurred

Examples

The following example demonstrates how to check error codes using the ErrorCode enum. ErrorCode members do not directly compare to integers; use the .value attribute for integer comparison.

from pyqpanda3.pilot_service.pilot_service import ErrorCode

# Simulate error codes as returned by service.query_result()
test_cases = [
    (0, ""),          # NO_ERROR_FOUND
    (35, "Offline"),  # ERR_CHIP_OFFLINE
    (6, ""),          # EXCEED_MAX_QUBIT
    (31, "Timeout"),  # ERR_TASK_TERMINATED
    (99, "Unknown"),  # Unrecognized error
]

for err_code, err_info in test_cases:
    if err_code == ErrorCode.NO_ERROR_FOUND.value:
        print("Operation succeeded")
    elif err_code == ErrorCode.ERR_CHIP_OFFLINE.value:
        print("The chip is offline; try a different backend")
    elif err_code == ErrorCode.EXCEED_MAX_QUBIT.value:
        print("Program uses too many qubits for this chip")
    elif err_code == ErrorCode.ERR_TASK_TERMINATED.value:
        print("Task was terminated")
    else:
        print(f"Error {err_code}: {err_info}")

Running the code above produces:

Operation succeeded
The chip is offline; try a different backend
Program uses too many qubits for this chip
Task was terminated
Error 99: Unknown

When using QPilotService.query_result(), the returned dict contains the error code as an integer in the errCode key:

from pyqpanda3.pilot_service import QPilotService
from pyqpanda3.pilot_service.pilot_service import ErrorCode

# service = QPilotService(url="https://qpilot.originquantum.cn", api_key="key")
# task_id = service.async_run(prog, shot=1000)
# result = service.query_result(task_id)
# err_code = result["errCode"]
# err_info = result.get("errInfo", "")

See Also

• QPilotService -- Service class that returns ErrorCode values
• PilotNoiseParams -- Noise parameter configuration