Error Reference

All error types thrown by the HUMΛN agent SDK. Every error extendsSDKError and carries a machine-readablecode string for reliable programmatic handling.

Import

typescript

import {
  SDKError,
  AccessDeniedError,
  NotFoundError,
  TimeoutError,
  NotImplementedError,
  BudgetExceededError,
  DelegationExpiredError,
  InvalidInputError,
} from '@human/agent-sdk';

Handling Errors

Use instanceof checks to distinguish error types. Not all errors are retryable — AccessDeniedError andBudgetExceededError will not resolve on retry.

typescript

import { AccessDeniedError, BudgetExceededError, TimeoutError } from '@human/agent-sdk';

export default handler({
  name: 'resilient-agent',
  execute: async (ctx, input) => {
    try {
      const response = await ctx.llm.complete({ prompt: input.query });
      return { result: response.content };

    } catch (err) {
      if (err instanceof BudgetExceededError) {
        // Delegation budget is exhausted — don't retry
        ctx.log.error('Budget exceeded', { budget: err.budget, spent: err.spent });
        return { error: 'budget_exceeded', message: 'Processing limit reached.' };
      }

      if (err instanceof AccessDeniedError) {
        // Missing delegation scope — not retryable
        ctx.log.warn('Access denied', { scope: err.requiredScope });
        return { error: 'unauthorized', message: 'Insufficient permissions.' };
      }

      if (err instanceof TimeoutError) {
        // LLM or agent call took too long — may be retryable
        ctx.log.warn('Operation timed out', { operation: err.operation });
        return { error: 'timeout', message: 'Operation took too long.' };
      }

      // Unknown error — re-throw to let the runtime handle it
      throw err;
    }
  },
});

Using Error Codes

typescript

// All SDK errors have a machine-readable code
try {
  await ctx.secrets.get('DB_PASSWORD');
} catch (err) {
  if (err instanceof SDKError) {
    console.log(err.code);     // 'ACCESS_DENIED'
    console.log(err.message);  // Human-readable message
    console.log(err.cause);    // Original error (if wrapped)
  }
}

All Error Types

SDKErrorSDK_ERROR

Base class for all SDK errors. All other error types extend this.

Additional fields

message: stringcode: stringcause?: unknown

Thrown by

Any ctx.* call on unexpected infrastructure failure.

AccessDeniedErrorACCESS_DENIED

The agent's delegation does not include the required scope for this operation.

Additional fields

requiredScope?: stringagentId: string

Thrown by

ctx.secrets.get(), ctx.llm.complete(), ctx.db.query(), ctx.call.agent(), ctx.prompts.load()

BudgetExceededErrorBUDGET_EXCEEDED

The operation would exceed the cost budget defined in the delegation.

Additional fields

budget: numberspent: numbercurrency: string

Thrown by

ctx.llm.complete(), ctx.llm.embed(), ctx.call.agent()

TimeoutErrorTIMEOUT

An operation exceeded its configured timeout.

Additional fields

operation: stringtimeoutMs: number

Thrown by

ctx.llm.complete(), ctx.call.agent(), ctx.call.human(), ctx.call.route()

DelegationExpiredErrorDELEGATION_EXPIRED

The delegation granted to this agent has expired.

Additional fields

expiredAt: numberdelegationId: string

Thrown by

Any ctx.* call after the delegation TTL.

NotFoundErrorNOT_FOUND

The requested resource (agent, passport, secret) does not exist.

Additional fields

resourceType: stringresourceId: string

Thrown by

ctx.call.agent(), ctx.secrets.get(), ctx.provenance.get()

InvalidInputErrorINVALID_INPUT

The input to the agent or method failed validation.

Additional fields

field?: stringexpected?: string

Thrown by

handler() execute function when input schema validation fails.

NotImplementedErrorNOT_IMPLEMENTED

The requested operation is not available in the current deployment or runtime.

Additional fields

operation: string

Thrown by

ctx.* calls on operations not supported by the current runtime.

Error Reference

Import

Handling Errors

Using Error Codes

All Error Types

See Also