API Reference
Error Codes and Responses
Pre-launch
Section
API Reference
Documentation category
Type
Guide
Technical reference
Summary
Complete SwssChain API error code reference: HTTP status codes, SwssChain-specific error codes, response shape, and JavaScript error handling patterns.
SWSS Foundation Notice

This documentation is restricted to authorised members of the SWSS Developer Community. Access is granted exclusively through SWSS DevHub, after KYB and SWSS Foundation approval.

All SwssChain GitHub repositories are private. Significant updates are currently deploying across the full SWSS Ecosystem. SDK and API specifications are subject to change at any time in accordance with security requirements and SwssChain Foundation governance decisions.

Join SWSS DevHub →Have a question? Use the Need Help? button below.
SDK Update Notice

SWSS SDK v2.1 is deploying across the ecosystem. API signatures may change during this period. Ensure your integration uses the latest schema from SWSS DevHub.

Article Content

Error Codes and Responses

All SwssChain API errors return a consistent JSON error response. HTTP status codes follow standard conventions. SwssChain-specific error codes provide detail beyond the HTTP status, enabling your application to handle each failure mode precisely rather than catching a generic error class.

Standard Error Response Shape

Every error response (regardless of endpoint, HTTP method, or failure mode) uses the following JSON structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error",
    "details": {},
    "timestamp": "2026-05-15T10:00:00Z",
    "requestId": "req_abc123xyz"
  }
}

The requestId is unique to each API call and can be provided to SWSS DevHub support when investigating specific request failures. The details field contains additional context when relevant: for example, a 400 INVALID_BLOCK_RANGE response includes the maximum and provided range values in details.

HTTP Status Codes

StatusMeaningCommon Causes
200 OKSuccessful requestNormal operation
202 AcceptedRequest received but resource not yet readyCERTIFICATE_PENDING: deed settled but certificate not yet issued
400 Bad RequestInvalid parameters or malformed request bodyInvalid address format, hash format, or range parameters
401 UnauthorizedAuthentication failedMissing or invalid API key
403 ForbiddenAuthenticated but not permittedAPI key does not have access to this endpoint or tier
404 Not FoundRequested resource does not existUnknown transaction hash, block number, or address with no history
429 Too Many RequestsRate limit exceededPer-second or per-day limit reached for this API key's tier
500 Internal Server ErrorUnexpected server-side errorContact DevHub with the requestId
503 Service UnavailableTemporary unavailabilityPlanned maintenance window or node temporarily behind chain tip

SwssChain-Specific Error Codes

CodeHTTP StatusDescription
UNAUTHORIZED401API key missing from request or cryptographically invalid
FORBIDDEN403Valid API key but insufficient permissions for this endpoint
NOT_FOUND404Requested resource does not exist on this chain
INVALID_ADDRESS400Malformed wallet address: must be 42-character 0x-prefixed hex
INVALID_HASH400Malformed transaction, block, or certificate hash: must be 66-character 0x-prefixed hex
INVALID_BLOCK_RANGE400Block range exceeds the 100-block maximum per request
DEED_NOT_FOUND404No deed transaction exists at the provided hash
CERTIFICATE_NOT_FOUND404No Finality Certificate exists for the provided hash
CERTIFICATE_PENDING202Deed transaction confirmed but Finality Certificate not yet issued: retry after 2 to 3 seconds
RATE_LIMIT_EXCEEDED429Per-second or per-day rate limit exceeded for this API key's tier
INVALID_DEED_TYPE400Unrecognised deed type filter value: see valid values in Deed Settlement Endpoints
CHAIN_SYNC_DELAY503The serving node is temporarily behind the chain tip: data may be stale, retry in a few seconds
INTERNAL_ERROR500Unexpected server error: provide requestId to DevHub support

Error Handling in JavaScript

async function callApi(endpoint) {
  const response = await fetch(
    'https://swssscan.swss.io/api/v1' + endpoint,
    { headers: { 'X-API-Key': process.env.SWSSCHAIN_API_KEY } }
  );

  if (response.status === 202) {
    // CERTIFICATE_PENDING — deed confirmed, cert not yet issued
    throw new Error('CERTIFICATE_PENDING: retry in 2-3 seconds');
  }

  if (!response.ok) {
    const body = await response.json();
    throw new Error(`${body.error.code}: ${body.error.message}`);
  }

  return response.json();
}

Special Case: CERTIFICATE_PENDING

The CERTIFICATE_PENDING code (HTTP 202) is unique among the error codes in that it does not represent a failure. It means a deed transaction has been confirmed and included in a finalised block, but the BFTFA round that produces the Finality Certificate has not yet completed. On SwssChain's 1-second block time, certificates are issued within the same block finalisation cycle in normal operation. If you receive CERTIFICATE_PENDING, wait 2 to 3 seconds and retry the certificate endpoint.

Next Steps

  • See Authentication and API Keys for resolving UNAUTHORIZED and FORBIDDEN errors.
  • See Rate Limits and Throttling for handling RATE_LIMIT_EXCEEDED with exponential backoff.
  • See the relevant endpoint reference pages for INVALID_DEED_TYPE, INVALID_BLOCK_RANGE, and DEED_NOT_FOUND resolution.