ArcherDB Error Codes Reference

This document provides a complete reference for all ArcherDB error codes.

Error Code Ranges

Retry Semantics

Errors are classified into three categories:

• Retryable: Transient errors that may succeed on retry (e.g., leader election, network issues)
• Client Error: Invalid request that will always fail (fix the request, don’t retry)
• Fatal: Server-side bugs (open an issue with logs and reproduction details)

Distributed Error Codes

Multi-Region Errors (213-218)

These errors occur in multi-region deployments with async replication.

Usage Notes:

• Code 213: Writes must go to the primary region. SDKs automatically route writes to primary.
• Code 214: The follower hasn’t caught up with replication. Wait and retry, or use a fresher replica.
• Code 215: The primary region is down. Wait for failover or recovery.
• Code 216: Cross-region replication is slow. Retry with backoff.
• Code 217: Concurrent writes to the same entity detected in active-active replication. Application needs conflict resolution.
• Code 218: Entity’s geo-shard doesn’t match the region handling the request. Check shard routing configuration.

Sharding Errors (220-224)

These errors occur in sharded cluster deployments.

Usage Notes:

• Code 220: SDKs automatically refresh topology and retry. No application action needed.
• Code 221: Wait for shard recovery. The cluster may be experiencing failures.
• Code 222: Wait for resharding to complete. Operations will succeed after.
• Code 223: The requested shard count is not valid (e.g., must be power of 2).
• Code 224: A resharding operation failed. Check cluster health.

Security Boundary Errors (410-414, reserved/legacy)

These codes are reserved for deployments that layer external security controls around ArcherDB.

Usage Notes:

• Code 410: Check external key management service availability and IAM/policy bindings.
• Code 411: Validate storage snapshot integrity and external decryption path.
• Code 412: Verify infrastructure policy requires encrypted storage/transport for this route.
• Code 413: Retry after external key rotation completes.
• Code 414: Align external tooling format/version with deployment standards.

SDK Error Handling

Python

from archerdb import (
    MultiRegionError,
    ShardingError,
    MultiRegionException,
    ShardingException,
    is_retryable,
)

try:
    result = client.query_radius(lat, lon, radius)
except ShardingException as e:
    if e.error == ShardingError.RESHARDING_IN_PROGRESS:
        # Wait and retry - cluster is resharding
        time.sleep(5)
        result = client.query_radius(lat, lon, radius)
    elif is_retryable(e.code):
        # Generic retry logic
        result = retry_with_backoff(lambda: client.query_radius(lat, lon, radius))
    else:
        raise  # Non-retryable error

Java

import com.archerdb.geo.ShardingError;
import com.archerdb.geo.ArcherDBException;

try {
    QueryResult result = client.queryRadius(lat, lon, radius);
} catch (ArcherDBException e) {
    ShardingError shardError = ShardingError.fromCode(e.getErrorCode());
    if (shardError != null && shardError.isRetryable()) {
        // Retry with backoff
    }
}

Go

import "github.com/ArcherDB-io/archerdb/src/clients/go/pkg/errors"

result, err := client.QueryRadius(lat, lon, radius)
if err != nil {
    if archerErr, ok := err.(*errors.ArcherDBError); ok {
        if errors.IsShardingError(int(archerErr.Code)) {
            if errors.IsRetryable(int(archerErr.Code)) {
                // Retry with backoff
            }
        }
    }
}

Node.js/TypeScript

import {
    ShardingError,
    ShardingException,
    isShardingError,
    isRetryable,
} from 'archerdb';

try {
    const result = await client.queryRadius(lat, lon, radius);
} catch (e) {
    if (e instanceof ShardingException) {
        if (e.error === ShardingError.RESHARDING_IN_PROGRESS) {
            // Wait and retry
            await sleep(5000);
            result = await client.queryRadius(lat, lon, radius);
        }
    }
}

Troubleshooting Guide

Multi-Region Issues

Sharding Issues

Security Boundary Issues (410-414)

Related Documentation

• SDK Retry Semantics - Detailed retry configuration
• Disaster Recovery - Recovery procedures
• Operations Runbook - Operational procedures