​
Error Handling

QuantumSafe API returns structured error responses with consistent error codes. All errors follow this format: 
{
  "error": {
    "code": "AUTH_001",
    "message": "API key is missing or malformed",
    "details": {}
  }
}

​
Error Code Reference

​
Authentication Errors (AUTH)

CodeHTTP StatusMessageResolution
AUTH_001401API key is missing or malformedInclude a valid API key in the Authorization: Bearer header
AUTH_002401API key is invalid or revokedCheck that your key is active in the dashboard
AUTH_003403Insufficient permissionsPublishable keys cannot access this endpoint. Use a Secret key
AUTH_004403Environment mismatchTestnet key used against mainnet endpoint (or vice versa)
AUTH_005401Account suspendedContact support

​
Rate Limit Errors (RATE)

CodeHTTP StatusMessageResolution
RATE_001429Rate limit exceededWait for the duration specified in Retry-After header

​
PQC Errors (PQC)

CodeHTTP StatusMessageResolution
PQC_001400Unsupported algorithmUse a supported algorithm: ml-dsa-44, ml-dsa-65, ml-dsa-87, slh-dsa-128s
PQC_002400Invalid key formatEnsure keys are hex-encoded and match the specified algorithm
PQC_003400Key generation failedRetry the request. If persistent, check CSPRNG availability
PQC_004422Signature verification failedThe PQC or ECDSA signature does not match the provided message and public key

​
Scanner Errors (SCAN)

CodeHTTP StatusMessageResolution
SCAN_001400Invalid address formatCheck the address format for the specified chain
SCAN_002400Unsupported chainSee supported chains in the API reference
SCAN_003404Address not foundThe address has no on-chain activity
SCAN_004503Chain data unavailableThe chain data provider is temporarily unavailable. Retry later

​
Key Generation Errors (GEN)

CodeHTTP StatusMessageResolution
GEN_001400Invalid algorithm/chain combinationCheck the algorithm compatibility matrix
GEN_002500Internal generation errorRetry the request. If persistent, contact support

​
Handling Errors in SDKs

Both SDKs throw typed exceptions: 
import { QuantumSafeError } from "@quantumsafe/sdk";

try {
  const keypair = await qs.keys.generate({
    algorithm: "ml-dsa-65",
    chain: "ethereum",
  });
} catch (err) {
  if (err instanceof QuantumSafeError) {
    console.error("Code:", err.code);       // "AUTH_003"
    console.error("Message:", err.message); // "Insufficient permissions"
    console.error("Status:", err.status);   // 403
  }
}

​
Retry Strategy

For transient errors (5xx, SCAN_004, RATE_001), use exponential backoff: 
const MAX_RETRIES = 3;

async function withRetry(fn: () => Promise<any>) {
  for (let i = 0; i < MAX_RETRIES; i++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429) {
        const retryAfter = parseInt(err.headers["retry-after"] || "1");
        await sleep(retryAfter * 1000);
      } else if (err.status >= 500) {
        await sleep(Math.pow(2, i) * 1000);
      } else {
        throw err; // Non-retryable
      }
    }
  }
}