Error Handling

import {
  GrantexError,
  GrantexApiError,
  GrantexAuthError,
  GrantexTokenError,
  GrantexNetworkError,
} from '@grantex/sdk';

GrantexError (base)
├── GrantexApiError (HTTP 4xx/5xx)
│   └── GrantexAuthError (HTTP 401/403)
├── GrantexTokenError (JWT verification failures)
└── GrantexNetworkError (timeout, DNS, connection)

try {
  await grantex.agents.get('ag_nonexistent');
} catch (err) {
  if (err instanceof GrantexError) {
    console.error('Grantex SDK error:', err.message);
  }
}

try {
  await grantex.agents.get('ag_nonexistent');
} catch (err) {
  if (err instanceof GrantexApiError) {
    console.error('Status:', err.statusCode);   // 404
    console.error('Body:', err.body);            // { message: 'Agent not found' }
    console.error('Request ID:', err.requestId); // 'req_01HXYZ...'
  }
}

try {
  const grantex = new Grantex({ apiKey: 'invalid-key' });
  await grantex.agents.list();
} catch (err) {
  if (err instanceof GrantexAuthError) {
    console.error('Auth failed:', err.statusCode); // 401 or 403
    console.error('Message:', err.message);         // 'Invalid API key'
  }
}

import { verifyGrantToken, GrantexTokenError } from '@grantex/sdk';

try {
  await verifyGrantToken('invalid.jwt.token', {
    jwksUri: 'https://api.grantex.dev/.well-known/jwks.json',
  });
} catch (err) {
  if (err instanceof GrantexTokenError) {
    console.error('Token error:', err.message);
    // "Grant token verification failed: ..."
    // "Grant token is missing required scopes: payments:initiate"
    // "Grant token is missing required claims (jti, sub, agt, dev, scp, iat, exp)"
  }
}

try {
  const grantex = new Grantex({
    apiKey: 'gx_...',
    baseUrl: 'https://unreachable.example.com',
    timeout: 5000,
  });
  await grantex.agents.list();
} catch (err) {
  if (err instanceof GrantexNetworkError) {
    console.error('Network error:', err.message);
    // "Request timed out after 5000ms"
    // "Network error: getaddrinfo ENOTFOUND unreachable.example.com"
    console.error('Cause:', err.cause); // The underlying error
  }
}

import {
  Grantex,
  GrantexAuthError,
  GrantexApiError,
  GrantexTokenError,
  GrantexNetworkError,
  GrantexError,
} from '@grantex/sdk';

const grantex = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

try {
  const agent = await grantex.agents.get('ag_01HXYZ...');
  console.log(agent.name);
} catch (err) {
  if (err instanceof GrantexAuthError) {
    // 401/403 -- API key is invalid or lacks permission
    console.error(`Authentication failed (${err.statusCode}): ${err.message}`);
    // Prompt user to re-authenticate or check API key
  } else if (err instanceof GrantexApiError) {
    // Other HTTP errors (404, 422, 429, 500, etc.)
    console.error(`API error (${err.statusCode}): ${err.message}`);
    if (err.requestId) {
      console.error(`Request ID: ${err.requestId} -- include this in support tickets`);
    }
  } else if (err instanceof GrantexNetworkError) {
    // Timeout, DNS, connection refused
    console.error(`Network error: ${err.message}`);
    // Retry with exponential backoff
  } else if (err instanceof GrantexTokenError) {
    // Token verification failure
    console.error(`Token error: ${err.message}`);
  } else if (err instanceof GrantexError) {
    // Catch-all for any other SDK error
    console.error(`Grantex error: ${err.message}`);
  } else {
    throw err; // Unexpected error -- rethrow
  }
}