Error Handling

1
import {
2
  RecursivError,
3
  AuthenticationError,
4
  AuthorizationError,
5
  NotFoundError,
6
  ValidationError,
7
  RateLimitError,
8
  ConflictError,
9
} from '@recursiv/sdk';

1
try {
2
  await r.users.me();
3
} catch (err) {
4
  if (err instanceof AuthenticationError) {
5
    // err.status === 401
6
    // err.code === 'invalid_api_key' | 'missing_api_key' | 'expired_api_key'
7
    console.error('Authentication failed:', err.message);
8
  }
9
}

1
try {
2
  await r.projects.delete('proj_123');
3
} catch (err) {
4
  if (err instanceof AuthorizationError) {
5
    // err.status === 403
6
    // err.code === 'insufficient_scopes' | 'forbidden'
7
    console.error('Not authorized:', err.message);
8
  }
9
}

1
try {
2
  await r.projects.get('nonexistent_id');
3
} catch (err) {
4
  if (err instanceof NotFoundError) {
5
    // err.status === 404
6
    console.error('Resource not found:', err.message);
7
  }
8
}

1
try {
2
  await r.agents.create({
3
    name: '',      // name is required
4
    username: 'a', // too short (min 3 chars)
5
  });
6
} catch (err) {
7
  if (err instanceof ValidationError) {
8
    // err.status === 400
9
    // err.code === 'invalid_input'
10
    console.error('Validation failed:', err.message);
11
12
    // Inspect field-level errors from Zod
13
    if (err.details) {
14
      console.error('Field errors:', JSON.stringify(err.details, null, 2));
15
    }
16
  }
17
}

1
try {
2
  await r.agents.chat('agent_123', { message: 'Hello' });
3
} catch (err) {
4
  if (err instanceof RateLimitError) {
5
    // err.status === 429
6
    // err.retryAfter — seconds to wait before retrying
7
    // err.upgradeUrl — 'https://recursiv.io/billing'
8
    console.error(`Rate limited. Retry after ${err.retryAfter}s`);
9
10
    // Wait and retry
11
    if (err.retryAfter) {
12
      await new Promise((resolve) => setTimeout(resolve, err.retryAfter! * 1000));
13
      // retry the request...
14
    }
15
  }
16
}

1
try {
2
  await r.agents.create({
3
    name: 'My Agent',
4
    username: 'existing_username',
5
  });
6
} catch (err) {
7
  if (err instanceof ConflictError) {
8
    // err.status === 409
9
    // err.code === 'username_taken' | 'already_exists'
10
    console.error('Conflict:', err.message);
11
  }
12
}

1
import {
2
  Recursiv,
3
  RecursivError,
4
  AuthenticationError,
5
  AuthorizationError,
6
  NotFoundError,
7
  ValidationError,
8
  RateLimitError,
9
  ConflictError,
10
} from '@recursiv/sdk';
11
12
const r = new Recursiv();
13
14
try {
15
  await r.projects.deploy('proj_123', { branch: 'main' });
16
} catch (err) {
17
  if (err instanceof ValidationError) {
18
    console.error('Invalid input:', err.details);
19
  } else if (err instanceof AuthenticationError) {
20
    console.error('Bad API key — check RECURSIV_API_KEY');
21
  } else if (err instanceof AuthorizationError) {
22
    console.error('Missing permissions:', err.message);
23
  } else if (err instanceof NotFoundError) {
24
    console.error('Resource not found');
25
  } else if (err instanceof RateLimitError) {
26
    console.error(`Rate limited. Retry in ${err.retryAfter}s`);
27
  } else if (err instanceof ConflictError) {
28
    console.error('Conflict:', err.message);
29
  } else if (err instanceof RecursivError) {
30
    // Catch-all for any other API error
31
    console.error(`API error [${err.status}]: ${err.message}`);
32
  } else {
33
    // Network error, timeout, etc.
34
    throw err;
35
  }
36
}

1
const r = new Recursiv({
2
  maxRetries: 3, // 1 initial request + 3 retries = 4 total attempts
3
});

1
const r = new Recursiv({ maxRetries: 0 });

1
try {
2
  const r = new Recursiv(); // no RECURSIV_API_KEY set
3
} catch (err) {
4
  if (err instanceof RecursivError) {
5
    // err.code === 'missing_api_key'
6
    console.error(err.message);
7
    // "No API key found. Set RECURSIV_API_KEY environment variable or pass apiKey to constructor."
8
  }
9
}