SDK Reference

Error handling

Every failed API call throws a typed error. Catch errors by class to handle specific scenarios.

Error hierarchy

StaffifyError              (base class)
  StaffifyAuthError        401. invalid or missing API key
  StaffifyPaymentError     402. account paused, no credits
  StaffifyPermissionError  403. insufficient permissions or org key required
  StaffifyNotFoundError    404. resource does not exist
  StaffifyConflictError    409. conflict (e.g. active call on deletion)
  StaffifyValidationError  400 / 422. bad request or validation failure
  StaffifyRateLimitError   429. rate limit exceeded (adds resetAt: Date)

Catching errors

TypeScript

import {
  StaffifyError,
  StaffifyAuthError,
  StaffifyNotFoundError,
  StaffifyRateLimitError,
  StaffifyValidationError,
} from 'staffify';

try {
  const { data } = await client.agents.get('agent_unknown');
} catch (err) {
  if (err instanceof StaffifyNotFoundError) {
    // 404. agent does not exist
    console.log('Not found:', err.message);

  } else if (err instanceof StaffifyRateLimitError) {
    // 429. rate limited
    console.log('Retry after:', err.resetAt); // Date object

  } else if (err instanceof StaffifyAuthError) {
    // 401. bad API key
    console.log('Auth error:', err.code);

  } else if (err instanceof StaffifyValidationError) {
    // 400/422. check your params
    console.log('Validation:', err.message);

  } else if (err instanceof StaffifyError) {
    // catch-all for any other Staffify error
    console.log(err.status, err.code, err.message, err.requestId);
  }
}

Error properties

Field	Type	Description
message	string	Human-readable description from the API
status	number	HTTP status code (401, 404, 429, etc.)
code	string	Machine-readable error code (e.g. INVALID_API_KEY, NOT_FOUND)
requestId	string \| undefined	Request ID from X-Request-Id header for support

StaffifyRateLimitError extra fields

Field	Type	Description
resetAt	Date \| null	When the rate limit window resets

Non-Staffify errors

Network failures, DNS errors, and timeouts throw standard JS errors (e.g. TypeError, AbortError), not StaffifyError. Always have a final catch that handles unknown errors.

← Configuration Pagination →