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 →