{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {
      // Additional context
    }
  }
}

try {
  await client.workOrders.create(/* ... */);
} catch (error) {
  if (error.status === 401) {
    if (error.code === 'INVALID_API_KEY') {
      // API key is wrong or revoked
      logger.error('Invalid API key - check configuration');
      throw new ConfigurationError('Invalid API key');
    }
    if (error.code === 'MISSING_API_KEY') {
      // API key not provided
      logger.error('API key not configured');
      throw new ConfigurationError('API key required');
    }
  }
  throw error;
}

try {
  await client.workOrders.create(/* ... */);
} catch (error) {
  if (error.status === 402 && error.code === 'INSUFFICIENT_CREDITS') {
    const { required, available } = error.details;

    // Option 1: Notify user
    await notifyUser(`Insufficient credits: need ${required}, have ${available}`);

    // Option 2: Queue for later
    await queueForLater(workOrder);

    return { status: 'insufficient_credits', required, available };
  }
  throw error;
}

async function withRateLimitRetry<T>(fn: () => Promise<T>): Promise<T> {
  const maxRetries = 3;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        const retryAfter = error.headers?.['retry-after'] || Math.pow(2, attempt);
        logger.warn(`Rate limited, waiting ${retryAfter}s`);
        await sleep(retryAfter * 1000);
        continue;
      }
      throw error;
    }
  }

  throw new Error('Max retries exceeded');
}

// Usage
const workOrder = await withRateLimitRetry(() =>
  client.workOrders.create(/* ... */)
);

try {
  await client.workOrders.create({
    taskPrompt: '', // Invalid: empty
    workspaceSource: { type: 'git' } // Invalid: missing repository
  });
} catch (error) {
  if (error.status === 400 && error.code === 'INVALID_REQUEST') {
    const { errors } = error.details;

    // errors might be:
    // [
    //   { field: 'taskPrompt', message: 'must not be empty' },
    //   { field: 'workspaceSource.repository', message: 'is required' }
    // ]

    for (const err of errors) {
      logger.error(`Validation error: ${err.field} - ${err.message}`);
    }

    throw new ValidationError('Invalid work order', errors);
  }
  throw error;
}

async function withRetry<T>(
  fn: () => Promise<T>,
  options = { maxRetries: 3, baseDelay: 1000 }
): Promise<T> {
  const { maxRetries, baseDelay } = options;
  let lastError;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;

      // Only retry 5xx errors
      if (error.status >= 500) {
        const delay = baseDelay * Math.pow(2, attempt);
        logger.warn(`Server error, retrying in ${delay}ms`, { attempt, error });
        await sleep(delay);
        continue;
      }

      throw error;
    }
  }

  throw lastError;
}

import {
  AgentGateError,
  AuthenticationError,
  AuthorizationError,
  ValidationError,
  PaymentError,
  NotFoundError,
  RateLimitError,
  ServerError
} from '@agentgate/sdk';

try {
  await client.workOrders.create(/* ... */);
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Handle auth issues
  } else if (error instanceof PaymentError) {
    // Handle credit issues
  } else if (error instanceof RateLimitError) {
    // Handle rate limiting
  } else if (error instanceof ServerError) {
    // Handle server errors
  } else if (error instanceof AgentGateError) {
    // Handle other API errors
  } else {
    // Handle non-API errors (network, etc.)
  }
}

const run = await client.runs.get(runId);

if (run.status === 'failed') {
  const { error } = run;

  switch (error.code) {
    case 'MAX_ITERATIONS_REACHED':
      // Task didn't converge
      logger.warn('Run did not converge', { runId, iterations: run.iterations });
      break;

    case 'VERIFICATION_FAILED':
      // Verification never passed
      logger.warn('Verification failed', { runId, details: error.details });
      break;

    case 'WORKSPACE_ERROR':
      // Problem with workspace setup
      logger.error('Workspace error', { runId, details: error.details });
      break;

    default:
      logger.error('Run failed', { runId, error });
  }
}

app.post('/webhooks/agentgate', async (req, res) => {
  res.sendStatus(200);

  const event = req.body;

  if (event.type === 'run.failed') {
    const { runId, error, tenantContext } = event.data;

    // Log for debugging
    logger.error('Run failed', { runId, error });

    // Notify affected user
    if (tenantContext?.tenantUserId) {
      await notifyUser(tenantContext.tenantUserId, {
        type: 'run_failed',
        runId,
        message: error.message
      });
    }

    // Potentially retry
    if (error.code === 'MAX_ITERATIONS_REACHED') {
      // Maybe try with more iterations or refined prompt
      await retryWithAdjustments(event.data);
    }
  }
});

// Include correlation IDs
const requestId = generateId();

try {
  logger.info('Creating work order', { requestId });
  const workOrder = await client.workOrders.create(/* ... */);
  logger.info('Work order created', { requestId, runId: workOrder.runId });
} catch (error) {
  logger.error('Failed to create work order', {
    requestId,
    error: {
      code: error.code,
      message: error.message,
      status: error.status
    }
  });
  throw error;
}