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.
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.
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
| Status | Meaning | Common Causes |
|---|---|---|
| 200 OK | Successful request | Normal operation |
| 202 Accepted | Request received but resource not yet ready | CERTIFICATE_PENDING: deed settled but certificate not yet issued |
| 400 Bad Request | Invalid parameters or malformed request body | Invalid address format, hash format, or range parameters |
| 401 Unauthorized | Authentication failed | Missing or invalid API key |
| 403 Forbidden | Authenticated but not permitted | API key does not have access to this endpoint or tier |
| 404 Not Found | Requested resource does not exist | Unknown transaction hash, block number, or address with no history |
| 429 Too Many Requests | Rate limit exceeded | Per-second or per-day limit reached for this API key's tier |
| 500 Internal Server Error | Unexpected server-side error | Contact DevHub with the requestId |
| 503 Service Unavailable | Temporary unavailability | Planned maintenance window or node temporarily behind chain tip |
SwssChain-Specific Error Codes
| Code | HTTP Status | Description |
|---|---|---|
UNAUTHORIZED | 401 | API key missing from request or cryptographically invalid |
FORBIDDEN | 403 | Valid API key but insufficient permissions for this endpoint |
NOT_FOUND | 404 | Requested resource does not exist on this chain |
INVALID_ADDRESS | 400 | Malformed wallet address: must be 42-character 0x-prefixed hex |
INVALID_HASH | 400 | Malformed transaction, block, or certificate hash: must be 66-character 0x-prefixed hex |
INVALID_BLOCK_RANGE | 400 | Block range exceeds the 100-block maximum per request |
DEED_NOT_FOUND | 404 | No deed transaction exists at the provided hash |
CERTIFICATE_NOT_FOUND | 404 | No Finality Certificate exists for the provided hash |
CERTIFICATE_PENDING | 202 | Deed transaction confirmed but Finality Certificate not yet issued: retry after 2 to 3 seconds |
RATE_LIMIT_EXCEEDED | 429 | Per-second or per-day rate limit exceeded for this API key's tier |
INVALID_DEED_TYPE | 400 | Unrecognised deed type filter value: see valid values in Deed Settlement Endpoints |
CHAIN_SYNC_DELAY | 503 | The serving node is temporarily behind the chain tip: data may be stale, retry in a few seconds |
INTERNAL_ERROR | 500 | Unexpected 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
UNAUTHORIZEDandFORBIDDENerrors. - See Rate Limits and Throttling for handling
RATE_LIMIT_EXCEEDEDwith exponential backoff. - See the relevant endpoint reference pages for
INVALID_DEED_TYPE,INVALID_BLOCK_RANGE, andDEED_NOT_FOUNDresolution.
