​

Error Reference

​

Error Response Format

{
  "errorType": "error_code",
  "errorMessage": "Human-readable description"
}

​

HTTP Status Codes

​

HTTP 400 - Bad Request

​

invalid_request

{
  "errorType": "invalid_request",
  "errorMessage": "Missing required field: walletName"
}

• Check all required fields are present
• Verify request body matches the schema
• Validate parameter formats

​

malformed_transaction

{
  "errorType": "malformed_transaction",
  "errorMessage": "Invalid RLP encoding"
}

• Verify transaction encoding (RLP for EVM, base64 for Solana)
• Check all transaction fields are valid
• Ensure correct chain format

​

invalid_signature

{
  "errorType": "invalid_signature",
  "errorMessage": "Signature does not match transaction hash"
}

• Verify signing with correct key
• Check transaction wasn’t modified after signing
• Ensure correct network/chain ID

​

invalid_address

{
  "errorType": "invalid_address",
  "errorMessage": "Invalid Ethereum address format"
}

• Check address checksum (EVM)
• Verify address length
• Ensure correct chain format

​

HTTP 401 - Unauthorized

​

unauthorized

{
  "errorType": "unauthorized",
  "errorMessage": "Invalid API key"
}

• Verify API key is correct
• Check signature calculation
• Ensure timestamp is within 5 minutes

​

token_expired

{
  "errorType": "token_expired",
  "errorMessage": "Access token expired"
}

• Refresh the access token
• Re-authenticate if refresh fails

​

signature_mismatch

{
  "errorType": "signature_mismatch",
  "errorMessage": "Request signature verification failed"
}

• Verify canonical string format
• Check secret key is correct
• Ensure body matches exactly

​

wallet_auth_required

{
  "errorType": "wallet_auth_required",
  "errorMessage": "Wallet Auth Token required for signing operations"
}

• Include X-Wallet-Auth header
• Generate valid wallet auth token

​

HTTP 403 - Forbidden

​

forbidden

{
  "errorType": "forbidden",
  "errorMessage": "API key does not have permission for this operation"
}

• Check API key permissions
• Verify resource ownership
• Contact admin for access

​

policy_denied

{
  "errorType": "policy_denied",
  "errorMessage": "Transaction exceeds daily limit"
}

• Review applicable policies
• Request approval if available
• Adjust transaction parameters

​

HTTP 404 - Not Found

​

not_found

{
  "errorType": "not_found",
  "errorMessage": "Wallet not found"
}

• Verify resource ID is correct
• Check resource wasn’t deleted
• Ensure correct project/tenant

​

HTTP 409 - Conflict

​

already_exists

{
  "errorType": "already_exists",
  "errorMessage": "Wallet with this name already exists"
}

• Use a different name/identifier
• Check if resource can be reused

​

idempotency_error

{
  "errorType": "idempotency_error",
  "errorMessage": "Idempotency key was used with different request body"
}

• Generate new idempotency key
• Only reuse keys for identical requests

​

HTTP 429 - Rate Limited

​

rate_limit_exceeded

{
  "errorType": "rate_limit_exceeded",
  "errorMessage": "Rate limit exceeded. Retry after 60 seconds."
}

• Implement exponential backoff
• Cache responses where possible
• Contact support for limit increase

​

HTTP 500 - Internal Server Error

​

internal_server_error

{
  "errorType": "internal_server_error",
  "errorMessage": "An unexpected error occurred"
}

• Retry with exponential backoff
• Contact support if persistent
• Check status page

​

HTTP 502 - Bad Gateway

​

bad_gateway

{
  "errorType": "bad_gateway",
  "errorMessage": "Unable to connect to signing service"
}

• Retry after short delay
• Check status page
• Contact support if persistent

​

HTTP 503 - Service Unavailable

​

service_unavailable

{
  "errorType": "service_unavailable",
  "errorMessage": "Service is under maintenance"
}

• Wait and retry
• Check status page for updates

​

HTTP 504 - Gateway Timeout

​

timed_out

{
  "errorType": "timed_out",
  "errorMessage": "Request timed out"
}

• Retry with exponential backoff
• Simplify request if possible
• Check operation status before retrying

​

Error Handling Best Practices

async function withRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status >= 500 || error.status === 429) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

import { v4 as uuidv4 } from 'uuid';

// Generate unique key per logical operation
const idempotencyKey = uuidv4();

const response = await fetch(url, {
  headers: {
    'X-Idempotency-Key': idempotencyKey,
    ...otherHeaders
  }
});

function logError(error, context) {
  console.error({
    errorType: error.errorType,
    errorMessage: error.errorMessage,
    status: error.status,
    requestId: error.headers?.['x-request-id'],
    timestamp: new Date().toISOString(),
    ...context
  });
}