Handle Orbit Search API errors in your application

if (error.code === "invalid_api_key") {
  // Key was revoked or expired — trigger key rotation flow
  await rotateApiKey();
} else if (error.code === "missing_api_key_scope") {
  // Log a configuration error — this needs a human to fix
  logger.error("API key missing required scope", { code: error.code });
}

const VALIDATION_ERRORS = new Set([
  "developer_query_required",
  "developer_num_users_required",
  "developer_num_users_limit_exceeded",
  "developer_user_id_override_forbidden",
  "developer_search_replay_unsupported",
  "developer_profile_query_required",
  "developer_profile_query_too_long",
  "developer_profile_query_limit_invalid",
  "developer_profile_query_limit_exceeded",
  "developer_deep_search_field_unsupported",
  "developer_deep_search_input_required",
  "developer_deep_search_email_invalid",
  "developer_deep_search_phone_invalid",
  "developer_deep_search_linkedin_invalid",
  "developer_deep_search_field_invalid",
  "developer_deep_search_url_invalid",
  "developer_deep_search_run_shape_invalid",
  "developer_deep_search_request_id_invalid",
  "developer_deep_search_personalization_unsupported",
  "developer_deep_search_unprocessable_seed",
  "structured_intent_required",
  "structured_intent_invalid",
  "structured_intent_version_unsupported",
  "structured_intent_entity_clauses_unsupported",
  "structured_intent_server_owned_field",
]);

if (VALIDATION_ERRORS.has(error.code)) {
  // Do not retry — fix the request body
  throw new Error(`Invalid search request: ${error.code}`);
}

if (error.code === "search_directory_not_found") {
  // Directory was archived or deleted — check directory list
  const directories = await listDirectories(organizationId);
  logger.warn("Directory not found", { directoryId, directories });
} else if (error.code === "search_directory_access_api_key_forbidden") {
  // Key lacks a grant — needs an admin to add one
  logger.error("API key lacks directory grant", { code: error.code });
}

{
  "status": "failed",
  "error": {
    "code": "developer_api_credits_insufficient",
    "message": "Developer API credits are insufficient for this request",
    "requiredCredits": 2,
    "remainingCredits": 0
  }
}

if (error.code === "developer_api_key_rate_limited") {
  // Exponential backoff
  await sleep(backoffMs);
  return retry(request);
}

if (error.code === "developer_api_credits_insufficient") {
  const { requiredCredits, remainingCredits } = error;
  logger.warn("Insufficient credits", { requiredCredits, remainingCredits });
  // Notify operators or pause non-essential requests
}

if (error.code === "developer_api_idempotency_key_conflict") {
  // Bug in your code — you're reusing a key with different params
  throw new Error("Idempotency key reused with different parameters");
}

if (error.code === "developer_api_idempotency_key_refunded") {
  // Safe to retry — just generate a fresh key
  return retry({ ...request, idempotencyKey: crypto.randomUUID() });
}

if (error.code === "developer_profile_not_found") {
  // No credits were consumed — safe to skip or log
  logger.info("Profile not found, skipping", { profileId });
}